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:

Java
Python