V2.1 Upload Measurement Points


Upload the measurement point data of a device or logic asset, including file-type data.


This API is available in EnOS 2.1.0 and above.


Note

File-type data is not supported by EnOS Edge.

Operation Permissions


Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.


Required Service Required Operation Permission
Asset Write

Request Format

POST https://{integration-address}/connect-service/v2.1/integration?action=postMeasurepoint

Note

{integration-address}: The gateway address of message integration service. Log in to the EnOS Management Console and find it in Help > Environment Information .

Request Parameters (URI)

Name Location (Path/Query) Mandatory/Optional Data Type Description
orgId Query Mandatory String The organization ID which the asset belongs to. How to get orgId>>

Request Parameters (Header)

Request parameters (Header)
Name Mandatory/Optional Data Type Description
apim-accesstoken Mandatory String The access token obtained via token authentication. For more information, see Get Access Token

Request Parameters (Body)

The format of the request body is multipart/form-data, consisting of multiple form-data sections. For a request body:

  • There must only be one request message. The request message takes up the space of one form-data and its format is “request form-data”. The header and body of “request form-data” are shown in the tables below.
  • There can be one or multiple file form-data. If a request body contains file data, one file takes up the space of one file form-data. Its format is “file form-data”. The header of a “file form-data” is shown in the table below. If the body does not contain any file data, the body does not have to contain any file form-data.
Header of the request form-data
Name Mandatory/Optional Data Type Description
Content-Disposition Mandatory Content-Disposition: form-data; name=”enos-message” name is a constant that indicates the name of the request message.


Body of a request form-data
Name Mandatory/Optional Data Type Description
method Mandatory String The request method.
id Optional Integer The request message ID.
version Mandatory String The version number.
params Mandatory Array of Measurement Point Structs An array of Measurement Point Structs. See the table below for the structure of a Measurement Point Struct.
files Mandatory Map The mapping between files and asset attributes. Its value is a key-value pair File Name : File Mapping Struct. See the table below for the structure of a File Mapping Struct.
isRealtimeIntegration Optional Boolean
  • true (default): Real-time message integration.
  • false: Offline message integration.


Note

Use one of the following methods to specify the device:

  • Include the assetId in the Request
  • Include both productKey + deviceKey in the Request

Measurement Point Struct
Name Mandatory/Optional Data Type Description
assetId Optional (See Note above) String The asset ID. How to get assetID>>
productKey Optional (See Note above) String The product key. To be used with deviceKey.
deviceKey Optional (See Note above) String The device key. To be used with productKey.
time Mandatory Long Timestamp of the measurement point data
measurepoints Mandatory Map The format is a key-value pair Measurement point ID : Point value. If the Measurement point ID is a file-type, its value would be local://filename . local:// is the fixed header. filename is the file name.


File Mapping Struct
Name Mandatory/Optional Data Type Description
featureId Mandatory String The event ID.
assetId Optional String The asset ID.
productKey Optional String The product key of the asset.
deviceKey Optional String The device key of the asset.
md5 Optional String The MD5 of the file.
originalFilename Optional String The name of the file, which will be returned when downloading. If not specified, the filename will be randomly generated.
fileExt Optional String The filename extension, such as .zip and .gpg.
fileLength Optional Long The size of the file in bytes. The size used will be the value of Content-Length in the header of the file form-data, only when unable to get that value, this will be used instead.
Header of the file form-data
Name Mandatory/Optional Data Type Description
Content-Disposition Mandatory Content-Disposition: form-data; name=”enos-file”; filename=”yourFileName” Fixed parameter in the file form-data. Fields are separated by a semicolon (;). name is enos-file. filename indicates file name.
Content-Length Mandatory Long The size of the file in bytes.

Response Parameters

Name Data Type Description
code Integer Return code of a request. + 0 indicates success. + non-zero values indicates failure.
msg String The explanation to the return code. Its value is OK if the request is successful.
requestId String A unique ID to identify a request.

Error Codes

Code Type Description Solution
11400 illegal argument Parameter error when uploading device datapoints. Check the detailed error message in ‘message’ or ‘detail message’.
11400 deserialize enos-message payload error Error in parsing the payload of the device datapoint request. Ensure that the input JSON is valid.
11401 Unauthenticated Access token error when uploading device datapoints. Make sure the ‘apim-accesstoken’ in the request header is valid.
11400 external ids can not be empty Missing asset information when uploading device datapoints. Ensure that the required device and datapoint information is included in the request.
11403 missing permissions of requested resources Lack of write permissions for the corresponding organization’s assets. Ensure that the service account has been granted write access to the asset service.
11400 model validate failed Model validation failed, incorrect datapoint type or the datapoint does not exist in the model. Ensure that the ‘events’ parameter declared in the request is valid.
11400 unknown method Invalid method parameter when uploading device datapoints. Make sure the ‘method’ parameter declared in the request is valid.
11400 payload is empty Empty payload in the request when uploading device datapoints. Ensure that the request body is not empty.
11404 device not found Device not found. Verify that the device actually exists.
11404 TSLInstance not found Device does not exist. Add the device.
11500 parse error Internal service error. Contact the administrator for the detailed error message in ‘message’ or ‘detail message’.

Samples

Request Sample

url: https://{integration-address}/connect-service/v2.1/integration?action=postMeasurepoint&orgId=yourOrgId
method: POST
requestHeader:
{
  "apim-accesstoken":"yourAccessToken"
}

requestBody:
Request form-data
Content-Disposition: form-data; name="enos-message"
{
  "method": "integration.measurepoint.post",
  "id": "123",
  "version": "1.1",
  "params":[
    {
      "productKey": "productKey1",
      "deviceKey": "deviceKey1",
      "time": 1579580182824,
      "measurepoints": {
        "intMesurepintId1": 123,
        "fileMeasurepointId1":"local://filename1"
      }
    },
    {
      "assetId": "assetId2",
      "time": 1579580182824,
      "measurepoints": {
        "intMesurepintId2": 123,
        "fileMeasurepointId2":"local://filename2"
      }
    }
  ],
  "files": {
    "filename1": {
      "featureId": "fileMeasurepointId1",
      "produckKey": "productKey1",
      "deviceKey": "deviceKey1",
      "originalFilename": "test.txt",
      "fileExt": ".txt",
      "md5": "md5value1"
    },
    "filename2": {
      "featureId": "fileMeasurepointId2",
      "assetId": "assetId2",
      "md5": "md5value2",
      "fileLength": 1024000
    }
  }
}

File form-data
Content-Disposition: form-data; name="enos-file"; filename="filename1"
Content-Length: 1024000
<Content of file filename1>

File form-data
Content-Disposition: form-data; name="enos-file"; filename="filename2"
Content-Length: 1024000
<Content of filename2>

Response Sample

{
    "code":0,
    "msg":"OK",
    "requestId":"03902fcf-0d23-40f5-a8fd-0af0774cb533",
    "data":{}
}

SDK Samples


You can access the SDK samples for Connection Service on GitHub: