应用端设备访问 API

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

API 接入点

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

https://<endpoint>

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

API 一览

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

https://<endpoint>/app/device/v1/<AccessToken>/attributes

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

HTTP 身份认证

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

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

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

向设备下发属性

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

POST https://<endpoint>/app/device/v1/<AccessToken>/attributes

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

{
    "switch": false
}

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

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

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

获取设备属性

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

GET https://<endpoint>/app/device/v1/<AccessToken>/attributes

设备调用该 API 时，支持 GET 参数如下：

例如：

GET https://<endpoint>/app/device/v1/<AccessToken>/attributes?keys=temperature,humidity

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

{
  "result": 1,
  "attributes": {
    "temperature": 34.2,
    "humidity": 67
  }
}

更新云端属性

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

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

PUT https://<endpoint>/app/device/v1/<AccessToken>/attributes

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

{
    "location": "REGION.B332"
}

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

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

向设备下发命令

应用端向设备下发命令。

POST https://<endpoint>/app/device/v1/<AccessToken>/command/send

请求正文 JSON 格式如下：

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

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

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

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

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

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

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

向设备下发命令（同步）

命令下发 API 还支持同步调用方式，应用端向设备下发命令，可在 HTTP 响应消息中同步获得设备的命令回复消息。

POST https://<endpoint>/app/device/v1/<AccessToken>/command/sync/send

调用同步命令下发 API 时，请求的消息格式和异步命令下发是完全相同的。

调用 API 后，云平台并不会立即向应用端返回 HTTP 响应，而是会等待设备上报命令回复消息，等待时间为 5 秒。

如果在规定的时间内，设备上报合法的命令回复消息，那么应用端收到的 HTTP 响应正文如下：

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

以上的 command 部分正是设备上报的命令回复消息。

如果设备未在规定时间内上报命令回复消息，应用端会收到以下 HTTP 响应：

{
  "result": 0,
  "message": "Waiting for command sync reply timeout",
  "errcode": 410
}

同步命令下发 更像是应用端对设备的远程方法调用（RPC），为应用端可以快速请求设备并获得结果，提供了一个非常快捷的方法。

向设备下发自定义数据流

应用端向设备下发自定义数据流消息。

POST https://<endpoint>/app/device/v1/<AccessToken>/data/<identifier>/set?push_mode=<push_mode>

下发自定义数据必须在设备所属 设备类型 中创建 自定义数据流，并将自定义数据流的标识符，作为 API URL 中的 <identifier>。

这里举个例子，创建好的自定义数据流如下图：

若要对 MQTT 接入的设备下发该自定义数据，API URL 如下：

POST https://<endpoint>/app/device/v1/<AccessToken>/data/stream/set?push_mode=mqtt

若要对 TCP 接入的设备下发该自定义数据，API URL 如下：

POST https://<endpoint>/app/device/v1/<AccessToken>/data/stream/set?push_mode=tcp

根据自定义数据流的消息类型，API 请求正文的格式分为以下几种。

• 下发 HEX 消息格式，例如：

{
    "type": "hex",
    "msg": "02030010000185FC"
}

• 下发 Plaintext 消息格式

{
	"type": "text",
	"msg": "location,1,5,6,0"
}

• 下发 JSON 消息格式

{
	"type": "json",
	"msg": {
		"command": "openLock",
		"led": "ON",
        "stat": "011001"
	}
}

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

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

这时候，设备端可通过如下方式接收该自定义数据下发：

• 设备使用 MQTT 接入方式，通过订阅 自定义数据下发 主题接收该消息。
• 设备使用 TCP 接入方式，自动接收该消息。

API 调试

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

HTTP API 客户端工具

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

• Postman 官网open in new window
• Insomnia 官网open in new window