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` 一起使用，用于指定一个设备。如何获取设备的 productKey 信息>>
deviceKey	可选（见上述注解）	String	设备的 device key。与 `productKey` 一起使用，用于指定一个设备。如何获取设备的 deviceKey 信息>>
time	必需	Long	测点数据的时间戳。
measurepoints	必需	Map	内容为 “测点 ID:测点值” 格式的键值对。如果测点 ID 是文件类型，其值为 `local://filename` `local://` 是固定格式开头。 `filename` 为文件名称。

文件映射数据结构体¶
名称	必需/可选	数据格式	描述
featureId	必需	String	测点 ID。
assetId	可选	String	设备的 asset ID。如何获取Asset ID信息>>
productKey	可选	String	设备的 product key。如何获取 productKey 信息>>
deviceKey	可选	String	设备的 Device Key。如何获取设备的 deviceKey 信息>>
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	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 示例：

Java
Python