应用端设备访问 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

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

{
    "location": "REGION.B332"
}

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

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

向设备下发命令

应用端向设备下发命令。

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

消息格式如下：

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

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

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

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

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

普通的命令下发 API 是异步下发，也就是说，应用端调用命令下发 API 后，云平台便立即返回 HTTP 响应，这并不代表设备真实收到了命令消息，以及执行了命令中的相关任务。

如果应用端需要知晓设备是否实际执行了命令，需要通过和设备的后续通信来确认，例如设备执行命令后，上报属性或事件，应用端获取设备属性，或通过事件 WebHook URL 来获得设备最新状态。

向设备下发命令（同步）

应用端向设备下发命令，并在 HTTP 响应消息中同步获得设备的命令回复消息。

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

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

当设备收到命令下发后，云平台并没有立即向应用端返回 HTTP 请求，而是会等待设备上报命令回复消息，等待时间为 5 秒。

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

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

以上的 params 参数正式设备上报命令回复消息中的内容。

如果设备没有在规定的时间内上报命令回复消息，应用端便会等待超时，收到 HTTP 响应消息如下：

{
  "result": 0,
  "message": "Wait Command sync reply timeout",
  "errcode": 501
}

同步命令下发 更像是应用端对设备的远程方法调用（RPC），为应用端调用设备功能提供了一个非常快捷的方法。

向设备下发自定义数据流

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

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

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

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

若要对通过 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