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)¶
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.
Name |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|
Content-Disposition |
Mandatory |
Content-Disposition: form-data; name=”enos-message” |
|
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 |
isRealtimeIntegration |
Optional |
Boolean |
|
Note
Use one of the following methods to specify the device:
Include the
assetId
in the RequestInclude both
productKey
+deviceKey
in the Request
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 |
Optional (See Note above) |
String |
The device key. To be used with |
time |
Mandatory |
Long |
Timestamp of the measurement point data |
measurepoints |
Mandatory |
Map |
The format is a key-value pair |
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 |
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 (;). |
Content-Length |
Mandatory |
Long |
The size of the file in bytes. |
Response Parameters¶
Name |
Data Type |
Description |
---|---|---|
code |
Integer |
Return code of a request.
+ |
msg |
String |
The explanation to the return code. Its value is |
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: