V2.1 Upload Measurement Points¶
上传设备或逻辑资产测点数据。测点数据可以包含文件类型。
该 API 支持在 EnOS 2.1.0 及以上环境中使用。
注解
通过该 API 上传 EnOS Edge 设备测点数据时,暂不支持文件类型数据。
请求格式¶
POST https://{integration-address}/connect-service/v2.1/integration?action=postMeasurepoint
注解
{integration-address}:消息集成服务网关地址。该信息可登录 EnOS 管理控制台,在 帮助 > 环境信息 > HTTP 消息集成通道 中获取。
请求参数(URI)¶
名称 | 位置(Path/Query) | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|---|
orgId | Query | 必需 | String | 资产所属的组织 ID。如何获取 orgId 信息>> |
请求参数(Header)¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
apim-accesstoken | 必需 | String | 通过 token 认证获取的 access token。获取方法,参见 获取 Access Token。 |
请求参数(Body)¶
Body 格式为 multipart/form-data。其中包含了多个 form-data,其中:
- 必需包含且仅包含一个请求报文。请求报文占用一个 form-data,其格式为 “请求报文 form-data”。请求报文 form-data 的 header 和 body 格式参见下文表格。
- 可以包含一个或多个文件 form-data。如果 body 中包含了文件类型数据,每个文件占用一个 form-data,文件数据格式为 “文件 form-data”。“文件form-data” 类型的数据 header格式见下文表格。如果测点数据不包含文件类型数据,则不需要提供文件 form-data。
名称 | 必需/可选 | 数据格式 | 描述 |
---|---|---|---|
Content-Disposition | 必需 | Content-Disposition: form-data; name=”enos-message” | name 为常量,表示请求消息体名称。 |
名称 | 必需/可选 | 数据格式 | 描述 |
---|---|---|---|
method | 必需 | String | 请求方法。 |
id | 可选 | Int | 请求消息 ID。 |
version | 必需 | String | 版本号。 |
params | 必需 | 测点数据结构体 Array | 资产测点数据的列表,其格式见 测点数据结构体表。 |
files | Body 包含文件时必需,不包含文件时可选 | 文件映射 Map | 文件与资产测点映射关系,内容为 “文件名:文件映射数据结构体” 格式的键值对,其格式见 文件映射数据结构体表。 |
isRealtimeIntegration | 可选 | Boolean |
|
注解
以下非必选字段中,使用以下任意一种方法:
- 在请求中单独包含
assetId
以指定一个设备或一个逻辑资产 - 在请求中单独包含
productKey
与deviceKey
以指定一个设备
名称 | 必需/可选 | 数据格式 | 描述 |
---|---|---|---|
assetId | 可选(见上述注解) | String | 资产的 ID。如何获取 assetId 信息>> |
productKey | 可选(见上述注解) | String | 设备的 product key。与 deviceKey 一起使用,用于指定一个设备。 |
deviceKey | 可选(见上述注解) | String | 设备的 device key。与 productKey 一起使用,用于指定一个设备。 |
time | 必需 | Long | 测点数据的时间戳。 |
measurepoints | 必需 | Map | 内容为 “测点 ID:测点值” 格式的键值对。如果测点 ID 是文件类型,其值为 local://filename local:// 是固定格式开头。 filename 为文件名称。 |
名称 | 必需/可选 | 数据格式 | 描述 |
---|---|---|---|
featureId | 必需 | String | 测点 ID。 |
assetId | 可选 | String | 资产的 ID。 |
productKey | 可选 | String | 设备的 product key。 |
deviceKey | 可选 | String | 设备的 device key。 |
md5 | 可选 | String | 文件 MD5。 |
originalFilename | 可选 | String | 原始文件的名称,将在下载时返回。如果未指定,文件名为随机文件标识符。 |
fileExt | 可选 | String | 文件后缀,如 .zip 和 .gpg。 |
fileLength | 可选 | Long | 文件大小,单位字节。文件大小的值将以文件 form-data 的 header 里的 Content-Length 为准,只有在获取不到其值时才会获取 fileLength 的值。 |
名称 | 必需/可选 | 数据格式 | 描述 |
---|---|---|---|
Content-Disposition | 必需 | Content-Disposition: form-data; name=”enos-file”; filename=”yourFileName” | name 为固定值,filename 为对应文件名。 |
Content-Length | 必需 | Long | 文件大小,单位字节。 |
响应参数¶
名称 | 数据类型 | 描述 |
---|---|---|
code | Int | 请求返回状态值。0 表示请求成功,非 0 则表示请求失败。 |
msg | String | 对状态码的解释。请求成功则为 OK 。 |
requestId | String | 每次请求获取的 ID,用于唯一标识该次 API 请求。 |
错误码¶
代码 | 类型 | 描述 | 解决方法 |
---|---|---|---|
11400 | illegal argument | 上传设备测点时, 参数错误 | 详细错误信息原因由message或 detail message给出。 |
11400 | deserialize enos-message payload error | 上传设备测点时, 请求体payload解析错误 | 确认传入JSON有效 |
11401 | Unauthenticated | 上传设备测点时, access token错误 | 确保请求头中的``apim-accesstoken``有效 |
11400 | external ids can not be empty | 上传设备测点时, 更新资产为空 | 确保请求中声明了需要上传的设备及测点信息 |
11403 | missing permissions of requested resources | 没有对应组织的资产写权限 | 确保服务账号已被授予资产服务的写入策略。 |
11400 | model validate failed | 模型校验失败, 测点类型错误或测点在模型中不存在 | 确保请求中声明的 events 参数有效。 |
11400 | unknown method | 上传设备测点时, 方法参数无效 | 确保请求中声明的``method`` 参数有效。 |
11400 | payload is empty | 上传设备测点时, 请求体payload为空。 | 确保请求体不为空。 |
11404 | device not found | 设备未找到。 | 确认该设备确实存在。 |
11404 | TSLInstance not found | 设备不存在。 | 增加设备。 |
11500 | parse error | 内部服务错误 | 联系管理员, 详细错误信息原因由message或 detail message给出。 |
示例¶
请求示例¶
url: https://{integration-address}/connect-service/v2.1/integration?action=postMeasurepoint&orgId=yourOrgId
method: POST
requestHeader:
{
"apim-accesstoken":"yourAccessToken"
}
requestBody:
请求报文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": "file.txt",
"fileExt": ".txt",
"md5": "md5value1"
},
"filename2": {
"featureId": "fileMeasurepointId2",
"assetId": "assetId2",
"md5": "md5value2",
"fileLength": 1024000
}
}
}
文件form-data
Content-Disposition: form-data; name="enos-file"; filename="filename1"
Content-Length: 1024000
<文件filename1的内容>
文件form-data
Content-Disposition: form-data; name="enos-file"; filename="filename2"
Content-Length: 1024000
<文件filename2的内容>
返回示例¶
{
"code":0,
"msg":"OK",
"requestId":"03902fcf-0d23-40f5-a8fd-0af0774cb533",
"data":{}
}