V2.1 Upload Events¶

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

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

操作权限¶

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

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

请求格式¶

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

备注

{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	必需	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 信息>>
time	必需	Long	事件数据的时间戳。
events	必需	Map	内容为 “事件 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	模型校验失败, 事件类型错误或事件在模型中不存在	确保请求中声明的 `events` 参数有效。
11400	unknown method	上传事件时, 方法参数无效	确保请求中声明的``method`` 参数有效。
11400	payload is empty	上传事件时, 请求体payload为空。	确保请求体不为空。
11404	device not found	设备未找到。	确认该设备确实存在。
11500	parse error	内部服务错误	联系管理员, 详细错误信息原因由message或 detail message给出。

示例¶

请求示例¶

url: https://{integration-address}/connect-service/v2.1/integration?action=postEvent&orgId=yourOrgId
method: POST
requestHeader:
{
  "apim-accesstoken":"yourAccessToken"
}
requestBody:
请求报文form-data
Content-Disposition: form-data; name="enos-message"
{
  "method": "integration.event.post",
  "id": "123",
  "version": "1.1",
  "params":[
    {
      "productKey": "productKey1",
      "deviceKey": "deviceKey1",
      "time": 1579580182824,
      "events": {
        "eventId1":{
          "intParam1": 123,
          "fileParam1":"local://filename1"
        }
      }
    },
    {
      "assetId": "assetId2",
      "time": 1579580182824,
      "events": {
        "eventId2":{
          "intParam2": 123,
          "fileParam2":"local://filename2"
        }
      }
    }
  ],
  "files": {
    "filename1": {
      "featureId": "eventId1",
      "produckKey": "productKey1",
      "deviceKey": "deviceKey1",
      "originalFilename": "test.txt",
      "fileExt": ".txt",
      "md5": "md5value1"
    },
    "filename2": {
      "featureId": "eventId2",
      "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":"0b754708-5661-482e-8a9a-bc5916326d18",
    "data":{}
}

SDK 示例¶

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

Java
Python