V2.1 Upload Measurement Points


上传设备或逻辑资产测点数据。测点数据可以包含文件类型。

该 API 支持在 EnOS 2.1.0 及以上环境中使用。


注解

通过该 API 上传 EnOS Edge 设备测点数据时，暂不支持文件类型数据。

操作权限


使用此 API 前，确保服务账号已被授予包含下列服务和操作权限的策略。有关授权服务账号的更多信息，参见 管理服务账号。


需授权的服务 所需操作权限
资产 Write

请求格式

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

注解

{integration-address}：消息集成服务网关地址。该信息可登录 EnOS 管理控制台，在 帮助 > 环境信息 > HTTP 消息集成通道 中获取。

请求参数（URI）

名称 位置(Path/Query) 必需/可选 数据类型 描述
orgId Query 必需 String 资产所属的组织 ID。如何获取 orgId 信息>>

请求参数（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。
请求报文 form-data 的 header
名称 必需/可选 数据格式 描述
Content-Disposition 必需 Content-Disposition: form-data; name=”enos-message” name 为常量，表示请求消息体名称。


请求报文 form-data 的 body
名称 必需/可选 数据格式 描述
method 必需 String 请求方法。
id 可选 Int 请求消息 ID。
version 必需 String 版本号。
params 必需 测点数据结构体 Array 资产测点数据的列表，其格式见 测点数据结构体表。
files Body 包含文件时必需，不包含文件时可选 文件映射 Map 文件与资产测点映射关系，内容为 “文件名:文件映射数据结构体” 格式的键值对，其格式见 文件映射数据结构体表。
isRealtimeIntegration 可选 Boolean
  • true （默认）：实时消息集成。
  • false：离线消息集成。


注解

以下非必选字段中，使用以下任意一种方法：

  • 在请求中单独包含 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 的值。
文件 form-data 的 header
名称 必需/可选 数据格式 描述
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":{}
}

SDK 示例


你可以在 Github 上获取接入服务的 SDK 示例：