HTTP协议

入门
Key-value格式
遥测上传API
属性API
支持JSON
RPC API
- 服务器端RPC
- 客户端RPC
声明设备
设备预配置
硬件API
自定义协议
下一步

入门

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
telemetry-data-as-object.json
telemetry-data-as-array.json
telemetry-data-with-ts.json

# Publish data as an object without timestamp (server-side timestamp will be used). Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST --data "{"temperature":42,"humidity":73}" http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST --data "{"temperature":42,"humidity":73}" https://demo.thingsboard.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

# Publish data as an object without timestamp (server-side timestamp will be used) using data from file. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @telemetry-data-as-object.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @telemetry-data-as-object.json https://demo.thingsboard.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

# Publish data as an array of objects without timestamp (server-side timestamp will be used)  using data from file. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @telemetry-data-as-array.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @telemetry-data-as-array.json https://demo.thingsboard.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

# Publish data as an object with timestamp (telemetry timestamp will be used)  using data from file. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @telemetry-data-with-ts.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @telemetry-data-with-ts.json https://demo.thingsboard.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

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

[{"key1":"value1"}, {"key2":true}]

{
  "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
new-attributes-values.json

# Publish client-side attributes update. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" https://demo.thingsboard.io/api/v1/ABC123/attributes --header "Content-Type:application/json"

# Publish client-side attributes update from file. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @new-attributes-values.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @new-attributes-values.json https://demo.thingsboard.io/api/v1/ABC123/attributes --header "Content-Type:application/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
Result

# Send HTTP attributes request. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X GET "http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X GET "https://demo.thingsboard.io/api/v1/ABC123/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

{"client":{"attribute1":"value1","attribute2":true}}

请注意客户端和共享设备属性键的交集是不好的做法！但是对于客户端、共享和服务器端属性具有相同的密钥。

订阅属性

为了订阅共享设备属性更改请将带有可选”timeout”请求参数的GET请求发送到以下URL：

http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes/updates

一旦服务器端组件之一（REST API或规则链）更改了共享属性客户端将收到以下更新：

Example
Result

# Send subscribe attributes request with 20 seconds timeout. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X GET http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X GET https://demo.thingsboard.io/api/v1/ABC123/attributes/updates?timeout=20000

{"client":{"attribute1":"value1","attribute2":true}}

支持JSON

We added support of JSON data structures to telemetry and attributes API to simplify work with device configuration. JSON support allows you to both upload from the device, and push to device nested objects. You can store one configuration JSON as a shared attribute and push it to the device. You can also process the JSON data in the rule engine and raise alarms, etc.

Therefore, this improvement minimizes the number of Database operations when ThingsBoard stores the data. For example, “temperature” and “humidity” would be stored as separate rows in SQL or NoSQL databases in order to efficiently aggregate this data for visualization. Since there is no need to aggregate JSON data, we can store all the content as one row instead of separate rows for each configuration item. In some of our environments, it is possible to decrease the number of database operations more than 10 times by aggregating multiple parameters within one JSON.

Learn more about JSON value support with the video.

RPC API

服务器端RPC

为了从服务器订阅RPC命令请将带有可选的”timeout”请求参数的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对象

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

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

参见下面示例：

使用RPC debug terminal在仪表板调试
从服务器订阅RPC命令并在第一个终端窗口中带有observe标志的发送请求
将RPC请求”connect”发送到设备
在第二个终端窗口中模拟将响应从设备发送到服务器
收到设备的响应: {“result”:”ok”}

Subscribe to RPC commands from the server. To do this, in the first terminal window send GET request with observe flag

Send an RPC request "connect" to the device

In the second terminal window simulate send a response from the device to the server

You should receive a response from the device: {"result":"ok"}

Example Subscribe
Example Reply
Reply Body

# Send rpc request with 20 seconds timeout. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X GET http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc?timeout=20000
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X GET https://demo.thingsboard.io/api/v1/ABC123/rpc?timeout=20000

# Publish response to RPC request. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @rpc-response.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @rpc-response.json https://demo.thingsboard.io/api/v1/ABC123/rpc/1 --header "Content-Type:application/json"

{"result":"ok"}

客户端RPC

为了将RPC命令发送到服务器请将POST请求发送到以下URL：

http://host:port/api/v1/$ACCESS_TOKEN/rpc

请求和响应主体都应该是有效的JSON文档。

参见下面示例：

在规则链中添加两个节点”script”和”rpc call reply”
在script中输入函数：

return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};

将请求发送到服务器
收到服务器的响应

Add two nodes to the Rule Chain: "script" and "rpc call reply"

In the script node enter the function: return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};

You should receive a response from the server

Example Request
Request Body
Response Body

# Post client-side rpc request. Replace $THINGSBOARD_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -X POST -d @rpc-client-request.json http://$THINGSBOARD_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"
# For example, $THINGSBOARD_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -X POST -d @rpc-client-request.json https://demo.thingsboard.io/api/v1/ABC123/rpc --header "Content-Type:application/json"

{"method": "getCurrentTime", "params":{}}

{"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/etting/themings/conf/conf/thexboard.yml中使用）。

设备预配置

请参阅相应的文章并获取有关[设备供应]Device provisioning功能的更多信息。

启动设备配置请将发布请求发送到以下URL：

http(s)://host:port/api/v1/provision

支持数据格式如下：

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

硬件API

当Thingsboard通过HTTP启动固件更新时它会设置FW_TITLE，FW_VERSION，FW_CHECKSUM，FW_CHECKSUM_ALGORITHM共享属性。

要接收共享属性更新该设备必须获取请求。

http(s)://host/api/v1/${access_token}/firmware?title=${title}&version=${version}

说明
host - 本地主机或平台地址 ${access_token} - 设备访问令牌 ${title} - 固件标题 ${version} - 固件的目标版本

自定义协议

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

下一步

入门指南 - 快速学习ThingsBoard相关功能。
安装指南 - 学习如何在各种操作系统上安装ThingsBoard。
可视化 - 学习如何配置复杂的ThingsBoard仪表板说明。
数据处理 - 学习如何使用ThingsBoard规则引擎。
数据分析 - 学习如何使用规则引擎执行基本的分析任务。
硬件样品 - 学习如何将各种硬件平台连接到ThingsBoard。
高级功能 - 学习高级ThingsBoard功能。
开发指南 - 学习ThingsBoard中的贡献和开发。

本页目录