V2.1 Upload Attributes¶

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

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

操作权限¶

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

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

请求格式¶

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

备注

{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 格式见下文表格。如果 body 不包含文件类型数据，则不需要提供文件 form-data。

请求报文 form-data 的 header¶
名称	必需/可选	数据格式	描述
Content-Disposition	必需	Content-Disposition: form-data; name=”enos-message”	`name` 为常量，表示请求消息体名称。

请求报文 form-data 的 body¶
名称	必需/可选	数据格式	描述
method	必需	String	请求方法。
id	必需	Integer	请求消息 ID。
version	必需	String	版本号。
params	必需	属性数据结构体数组	资产属性数据的列表，其格式见属性数据结构体表。
files	body包含文件时必需，不包含文件时可选	文件映射 Map	文件与资产属性映射关系，内容为“文件名:文件映射数据结构体”格式的键值对，其格式见文件映射数据结构体表。

备注

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

在请求中单独包含 assetId 以指定一个设备或一个逻辑资产。
在请求中单独包含 productKey 与 deviceKey 以指定一个设备。

属性数据结构体¶
名称	必需/可选	数据格式	描述
assetId	可选（见上述注解）	String	资产的 ID。单独使用以指定一个设备或一个逻辑资产。如何获取 assetId 信息>>
productKey	可选（见上述注解）	String	设备的 product key。与 `deviceKey` 一起使用，用于指定一个设备。如何获取设备的 productKey 信息>>
deviceKey	可选（见上述注解）	String	设备的 device key。与 `productKey` 一起使用，用于指定一个设备。如何获取设备的 deviceKey 信息>>
attributes	必需	Map	内容为 “属性 ID:属性值” 格式的键值对。如果属性 ID 是文件类型，其值为 `local://filename`，`local://` 为固定格式开头，`filename` 为文件名称。如果属性值存在默认值且本次请求未传值，将使用默认值。

文件映射数据结构体¶
名称	必需/可选	数据格式	描述
featureId	必需	String	测点 ID。
assetId	可选	String	资产的 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	Integer	请求返回状态值。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	模型校验失败, 属性类型错误或属性在模型中不存在	确保请求中声明的 `attributes` 参数有效。
11400	unknown method	上传设备属性时, 方法参数无效	确保请求中声明的``method`` 参数有效。
11400	payload is empty	上传设备属性时, 请求体payload为空。	确保请求体不为空。
11400	update attribute failure	属性更新失败。	详细错误信息原因由message或 detail message给出。
11404	device not found	设备未找到。	确认该设备确实存在。
11500	parse error	内部服务错误	联系管理员, 详细错误信息原因由message或 detail message给出。

示例¶

请求示例¶

url: https://{integration-address}/connect-service/v2.1/integration?action=postAttribute&orgId=yourOrgId
method: POST
requestHeader:
{
  "apim-accesstoken":"yourAccessToken"
}
requestBody:

请求报文form-data
Content-Disposition: form-data; name="enos-message"
{
  "method": "integration.attribute.post",
  "id": "123",
  "version": "1.1",
  "params":[
    {
      "productKey": "productKey1",
      "deviceKey": "deviceKey1",
      "attributes": {
        "intAttibuteId1": 123,
        "fileAttibuteId1":"local://filename1"
      }
    },
    {
      "assetId": "assetId2",
      "attributes": {
        "intAttibuteId2": 123,
        "fileAttibuteId2": "local://filename2"
      }
    }
  ],
  "files": {
    "filename1": {
      "featureId": "fileAttibuteId1",
      "productKey": "productKey1",
      "deviceKey": "deviceKey1",
      "originalFilename": "test.txt",
      "fileExt": ".txt",
      "md5": "md5value1"
    },
    "filename2": {
      "featureId": "fileAttibuteId2",
      "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":"861bb9f0-f9db-4adf-bf5e-976e6943338e",
    "data":{}
}

SDK 示例¶

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

Java
Python