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: