Thingsboard API - HTTP API - 《Thingsboard 二次开发中文文档》

入门
- HTTP基础
客户端
HTTP身份验证
Key-value格式
遥测上传API
属性API
RPC API
- 服务器端RPC
- 客户端RPC
声明设备
自定义协议

入门

HTTP基础

HTTP是可在IoT应用程序中使用的通用网络协议。您可以在此处找到有关HTTP的更多信息。HTTP协议基于TCP，并使用请求-响应模型。
ThingsBoard服务器节点充当同时支持HTTP和HTTPS协议的HTTP Server。

客户端

您可以在网络上找到用于不同编程语言的HTTP客户端库。本文中的示例将基于curl。为了设置此工具，您可以使用我们的Hello World指南中的说明。

HTTP身份验证

我们将在本文中使用访问令牌设备凭证，这些凭证稍后将称为 $ACCESS_TOKEN。应用程序需要在每个HTTP请求中包括 $ACCESS_TOKEN 作为路径参数。可能的错误代码及其原因：

400 - 无效的请求地址.
401 - 无效的 $ACCESS_TOKEN.
404 - 未找到.

Key-value格式
ThingsBoard支持以JSON格式的key-value字符串，值可以是string、bool、float、long或者二进制格式的序列化字符串；有关更多详细信息请参见协议自定义。
例如:
```
{
"stringKey":"value1", 
"booleanKey":true, 
"doubleKey":42.0, 
"longKey":73, 
"jsonKey": {
  "someNumber": 42,
  "someArray": [1,2,3],
  "someNestedObject": {"key": "value"}
}
}
```
遥测上传API
为了将遥测数据发布到ThingsBoard服务器节点，请将POST请求发送到以下URL：
```
http(s)://host:port/api/v1/$ACCESS_TOKEN/telemetry
```
支持的最简单的数据格式是：
```
{"key1":"value1", "key2":"value2"}
```
或者
```
[{"key1":"value1"}, {"key2":"value2"}]
```
请注意 在这种情况下，服务器端时间戳将分配给上传的数据！
如果您的设备能够获得客户端时间戳，则可以使用以下格式:
```
{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}
```
在上面的示例中，我们假设“ 1451649600512”是具有毫秒精度的Unix时间戳。例如，值’1451649600512’对应于’星期五，2016年1月1日12：00：00.512 GMT’

Example

# Publish data as an object without timestamp (server-side timestamp will be used)
curl -v -X POST -d @telemetry-data-as-object.json http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
curl -v -X POST -d @telemetry-data-as-array.json http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# Publish data as an object with timestamp (server-side timestamp will be used)
curl -v -X POST -d @telemetry-data-with-ts.json http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

telemetry-data-as-object.json

{
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
  "someNumber": 42,
  "someArray": [1,2,3],
  "someNestedObject": {"key": "value"}
}
}

telemetry-data-as-array.json
```
[{"key1":"value1"}, {"key2":true}]
```

telemetry-data-with-ts.json

{
"ts": 1451649600512,
"values": {
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1, 2, 3],
    "someNestedObject": {
      "key": "value"
    }
  }
}
}

属性API

ThingsBoard属性API能够使设备具备如下功能

将客户端设备属性上载到服务器
从服务器请求客户端和共享设备属性
从服务器订阅共享设备属性

将属性更新发布到服务器
为了将客户端设备属性发布到ThingsBoard服务器节点，请将POST请求发送到以下URL：
```
http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes
```

Example

# Publish client-side attributes update
curl -v -X POST -d @new-attributes-values.json http://localhost:8080/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

new-attributes-values.json

{
"attribute1": "value1",
"attribute2": true,
"attribute3": 42.0,
"attribute4": 73,
"attribute5": {
  "someNumber": 42,
  "someArray": [1,2,3],
  "someNestedObject": {"key": "value"}
}
}

从服务器请求属性值

为了向ThingsBoard服务器节点请求客户端或共享设备属性，请将GET请求发送到以下URL：

http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Example

# Send HTTP attributes request
curl -v -X GET http://localhost:8080/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Result
```
{"key1":"value1"}
```
请注意，客户端和共享设备属性键的交集是不好的做法！但是，对于客户端，共享甚至服务器端属性，仍然可能具有相同的密钥。

从服务器订阅属性更新
为了订阅共享设备属性更改，请将带有可选“ timeout”请求参数的GET请求发送到以下URL：
```
http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes/updates
```
一旦服务器端组件之一（REST API或规则链）更改了共享属性，客户端将收到以下更新：

Example

# Send subscribe attributes request with 20 seconds timeout
curl -v -X GET http://localhost:8080/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

Result
```
{"key1":"value1"}
```
RPC API

服务器端RPC
为了从服务器订阅RPC命令，请将带有可选的“超时”请求参数的GET请求发送到以下URL：
```
http(s)://host:port/api/v1/$ACCESS_TOKEN/rpc
```
订阅后，如果没有对特定设备的请求，则客户端可以接收rpc请求或超时消息。RPC请求正文的示例如下所示：
```
{
"id": "1",
"method": "setGpio",
"params": {
  "pin": "23",
  "value": 1
}
}
```
id - 请求ID，int
method - RPC方法名称, string
params - -RPC方法参数，自定义json对象

并可以使用POST请求回复以下网址：

http://host:port/api/v1/$ACCESS_TOKEN/rpc/{$id}

其中 $id 是整数请求标识符。

Example Subscribe

# Send rpc request with 20 seconds timeout
curl -v -X GET http://localhost:8080/api/v1/$ACCESS_TOKEN/rpc?timeout=20000

Example Reply

# Publish response to RPC request
curl -v -X POST -d @rpc-response.json http://localhost:8080/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"

Reply Body
```
{"result":"ok"}
```
客户端RPC
为了将RPC命令发送到服务器，请将POST请求发送到以下URL：
```
http://host:port/api/v1/$ACCESS_TOKEN/rpc
```
请求和响应主体都应该是有效的JSON文档。这些文档的内容特定于将处理您的请求的规则节点。

Example Request

# Post client-side rpc request
curl -X POST -d @rpc-client-request.json http://localhost:8080/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"

Request Body
```
{"method": "getTime", "params":{}}
```
Response Body
```
{"time":"2016 11 21 12:54:44.287"}
```
声明设备
请参阅相应的文章以获取有关声明设备功能的更多信息。
为了启动声明设备，请将POST请求发送到以下URL：
```
http(s)://host:port/api/v1/$ACCESS_TOKEN/claim
```
支持的数据格式为：
```
{"secretKey":"value", "durationMs":60000}
```
请注意，以上字段是可选的。如果未指定secretKey，则使用空字符串作为默认值。如果durationMs毫秒未指定时，系统参数device.claim.duration被使用（在文件/etc/thingsboard/conf/thingsboard.yml）。

自定义协议
通过更改相应的模块，可以针对特定用例完全定制HTTP传输。

HTTP API

入门

HTTP基础

客户端

HTTP身份验证

Key-value格式

遥测上传API

属性API

将属性更新发布到服务器

从服务器请求属性值

从服务器订阅属性更新

RPC API

服务器端RPC

客户端RPC

声明设备

自定义协议