应用端设备访问 API

ZhiLian.Yun 应用端设备访问 API提供了一套面向应用的设备访问接口，帮助您在应用端通过 HTTP 协议快捷的访问设备，包括读取设备属性，向设备下发属性、更新属性、下发命令、下发自定义数据等。

提示 应用端设备访问 API 仅包含设备通信类操作，如需通过 API 访问更多项目资源，请浏览项目 HTTP API。

API 接入点

每个项目的 API 接入点可能不同，请您进入控制台设备详情的【连接】页面，获取设备的应用端 API 接入点， 例如：

https://<endpoint>

应用端设备访问 API 接入点统一使用HTTPs加密传输协议，同一个项目内的所有设备拥有相同的 API 接入点。

API 一览

功能	HTTP Method	HTTP URL
采集设备属性	POST	/api/v1/control/device/{deviceCode}/attribute_acquisition
向设备下发属性	POST	/api/v1/control/device/{deviceCode}/attributes
获取设备历史属性	GET	/api/v1/device/{deviceCode}/attribute/{key}/series
获取设备历史属性聚合	GET	/api/v1/device/{deviceCode}/attribute/{key}/aggregate
获取设备最新属性	GET	/api/v1/device/{deviceCode}/attributes
发送指令	POST	/api/v1/control/device/{deviceCode}/command

您只需要将以上的 HTTP URL 和接入点拼接即可获得最终 API URL。例如，向设备下发属性的完整 URL：

https://<endpoint>/api/v1/control/device/{deviceCode}/attributes

其中，deviceCode 在设备详情页的连接 > 设备证书中可以找到。

提示 如果需要在应用端获取设备的deviceCode，可以是用项目 HTTP API来获取一个或多个设备的该证书信息。

HTTP 身份认证

调用应用端设备访问 API 时，需要在HTTP Header中加入以下字段：

Content-Type: application/json
Project-Key:<ProjectKey>

其中，<ProjectKey>在设备详情页的连接 > 设备证书中可以找到，同一个项目下所有设备的<ProjectKey>相同。

向设备下发属性

应用端向设备下发属性，同时也会更新云平台的设备属性。

PSOT https://<endpoint>/api/v1/control/device/{deviceCode}/attributes

HTTP请求的正文部分，是JSON格式的消息结构。一个简单的属性下发消息如下：

{
  "result": 1,
  "ts": 1609143039050
}

这时候，设备端可通过 MQTT 订阅的属性下发主题接收到下发的消息。

获取设备属性

应用端获取设备的属性，实际上是应用端获取云平台的设备属性当前值。

GET https://<endpoint>/api/v1/device/{deviceCode}/attributes

调用成功后，HTTP 响应正文如下：

更新云端属性

应用端仅更新设备的云端属性，不下发给设备。云端属性的概念会在功能定义中用到，它是指一种类型的属性，只由应用端来读写，既不需要下发给设备，也不会从设备上报到云平台。

云端属性可以用来保存一些设备业务层信息，只在应用端使用。同时，这些信息又可以利用属性的一些方式，比如在消息规则中参与逻辑计算和业务处理。

PUT https://<endpoint>/app/device/v1/{deviceCode}/attributes

请求正文 JSON 格式和属性下发相同，例如：

{
    "location": "REGION.B332"
}

调用成功后，HTTP 响应正文如下：

{
  "result": 1,
  "ts": 1609143039050
}

向设备下发命令

应用端向设备下发命令。

POST https://<endpoint>/api/v1/control/device/{deviceCode}/command

请求正文 JSON 格式如下：

{
    "method": "{name}",
    "params": {
        "key1": "{value1}",
        "key2": "{value2}",
        ...
    },
    "id": {id}
}

{id}的取值为不超过 6 位的整数，例如：1000。

调用成功后，HTTP 响应正文如下：

{
  "result": 1,
  "ts": 1609143039050
}

这时候，设备端可通过 MQTT 订阅的命令下发主题接收到下发的消息。

普通的命令下发 API 采用异步调用方式，也就是说，应用端调用命令下发 API 后，会立即收到 HTTP 响应，请注意，这并不代表设备实际收到了命令消息，以及执行了命令中的相关任务。

如果应用端需要知晓设备是否执行了命令，需要通过和设备的后续通信来确认，例如设备执行命令后，上报属性或事件，应用端主动读取设备属性，或通过 MQTT 应用端订阅服务来实时接收设备的属性和事件更新。

API 调试

应用端接入云平台的开发过程中，您可以通过多种方式快速调试和熟悉 API，并验证消息收发通信。

HTTP API 客户端工具

使用 HTTP API 客户端工具，例如：

• Postman官网

• Insomnia官网