HTTP是一种通用网络协议，可用于物联网应用。更多信息请参见此处。HTTP协议基于TCP，采用请求-响应模型。
ThingsBoard服务节点充当HTTP服务器，支持HTTP与HTTPS协议。
客户端库配置
不同平台和语言均有多种HTTP客户端库可供使用。本文示例基于curl。
Linux安装curl
1
sudo apt-get install curl
从Windows 10 build 17063与macOS 10.2 6C115 (Jaguar) 起，cURL默认可用。
HTTP认证方式
ThingsBoard支持基于access token的认证以保护HTTP连接。每次HTTP请求时，客户端须在请求URL中包含access token。
本指南示例采用基于access token的认证。
错误码及原因：
- 400 Bad Request - URL、请求参数或请求体无效
- 401 Unauthorized - access token 无效
- 404 Not Found - 请求的资源不存在
Key-value 格式
默认情况下，ThingsBoard 支持 JSON 形式的 key-value 内容。Key 始终为字符串，value 可为 string、boolean、double、long 或 JSON。 例如：
1
2
3
4
5
6
7
8
9
10
11
{
"stringKey":"value1",
"booleanKey":true,
"doubleKey":42.0,
"longKey":73,
"jsonKey": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
也可使用自定义二进制格式或序列化框架，详见协议自定义。
遥测上传API
向ThingsBoard服务节点发布遥测数据时，向以下URL发送POST请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry
⚠️ 其中
$ACCESS_TOKEN为设备的access token。
支持的最简数据格式为：
1
{"key1":"value1", "key2":"value2"}
or
1
[{"key1":"value1"}, {"key2":"value2"}]
此时，上传的数据将使用服务端时间戳！
若设备能获取客户端时间戳，可采用以下格式：
1
{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}
其中1451649600512为毫秒精度的Unix时间戳。 例如，’1451649600512’ 对应 ‘Fri, 01 Jan 2016 12:00:00.512 GMT’。
以下是发布不同类型遥测数据的命令示例。
⚠️ 请勿忘记替换：
$ACCESS_TOKEN为设备的access token。
示例1。
以对象形式发布无时间戳数据（将使用服务端时间戳）。
执行命令：
1
curl -v -X POST --data "{"temperature":42,"humidity":73}" https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
遥测数据：
1
{"temperature":42,"humidity":73}
示例2。
使用telemetry-data-as-object.json文件中的数据，以对象形式发布无时间戳数据（将使用服务端时间戳）。
执行命令：
1
curl -v -X POST -d @telemetry-data-as-object.json https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
JSON文件内容：
1
2
3
4
5
6
7
8
9
10
11
{
"stringKey": "value1",
"booleanKey": true,
"doubleKey": 42.0,
"longKey": 73,
"jsonKey": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
示例3。
使用telemetry-data-as-array.json文件中的数据，以对象数组形式发布无时间戳数据（将使用服务端时间戳）。
执行命令：
1
curl -v -X POST -d @telemetry-data-as-array.json https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
JSON文件内容：
1
[{"key1":"value1"}, {"key2":true}]
示例4。使用telemetry-data-with-ts.json文件中的数据，以带时间戳的对象形式发布数据（将使用遥测时间戳）。
执行命令：
1
curl -v -X POST -d @telemetry-data-with-ts.json https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
JSON文件内容：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"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服务节点发布客户端设备属性时，向以下URL发送POST请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes
其中
$ACCESS_TOKEN为设备的access token。
以下是发布不同类型属性数据的命令示例。
示例1。
发布客户端属性更新
1
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
示例2。
使用new-attributes-values.json文件发布客户端属性更新。
1
curl -v -X POST -d @new-attributes-values.json https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
JSON文件内容：
1
2
3
4
5
6
7
8
9
10
11
{
"attribute1": "value1",
"attribute2": true,
"attribute3": 42.0,
"attribute4": 73,
"attribute5": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
向服务器请求属性值
向ThingsBoard服务节点请求客户端或共享设备属性时，向以下URL发送GET请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
其中
$ACCESS_TOKEN为设备的access token。
1
curl -v -X GET "https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"
结果：
1
{"client":{"attribute1":"value1","attribute2":true}}
注意
客户端属性与共享设备属性的key相同是不推荐做法！ 但仍可对client、shared甚至server-side属性使用相同key。
订阅服务器属性更新
订阅共享设备属性变更时，向以下URL发送带可选”timeout”请求参数的GET请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes/updates
其中
$ACCESS_TOKEN为设备的access token。
当共享属性被任一服务端组件（REST API或Rule Chain）修改后，客户端将收到如下更新：
1
curl -v -X GET https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000
结果：
1
{"client":{"attribute1":"value1","attribute2":true}}
JSON value support
我们为遥测和属性 API 增加了 JSON 数据结构支持，以便简化设备配置操作。 JSON 支持允许从设备上传数据，并将嵌套对象推送到设备。 可将一份配置 JSON 存为共享属性并推送到设备，也可在规则引擎中处理 JSON 数据并触发告警等。
因此，该改进在ThingsBoard 存储数据时减少了数据库操作次数。 例如，「temperature」和「humidity」会作为独立行存储在 SQL 或 NoSQL 数据库中，以便高效聚合用于可视化。 由于 JSON 数据无需聚合，可将全部内容存为一行，而无需为每个配置项单独成行。 在某些环境中，通过在单个 JSON 中聚合多个参数，可将数据库操作次数减少 10 倍以上。
通过该 视频 了解更多 JSON 值支持内容。
RPC API
服务端RPC
订阅来自服务器的RPC命令时，向以下URL发送带可选 “timeout” 请求参数的GET请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/rpc
其中
$ACCESS_TOKEN为设备的access token。
订阅后，客户端可能收到RPC请求；若该设备无待处理请求，则可能收到超时消息。 RPC请求体示例见下：
1
2
3
4
5
6
7
8
{
"id": "1",
"method": "setGpio",
"params": {
"pin": "23",
"value": 1
}
}
其中
• id - 请求id，整型请求标识符
• method - RPC方法名，字符串
• params - RPC方法参数，自定义JSON对象
可通过向以下URL发送POST请求回复：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/rpc/{$id}
其中
$id为整型请求标识符。
示例说明：
- 在ThingsBoard实例中使用 RPC调试终端部件；
- 使用下方命令订阅来自服务器的RPC命令：在第一个终端窗口发送带observe标志的GET请求。
1
curl -v -X GET https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/rpc?timeout=20000
其中
$ACCESS_TOKEN为设备的access token。
- 使用 RPC调试终端部件向设备发送RPC请求 “connect”；
- 将rpc-response.json保存到您的PC；
- 在第二个终端窗口模拟设备向服务器发送响应：
1
curl -v -X POST -d @rpc-response.json https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"
应收到来自设备的响应：
1
{"result":"ok"}
客户端RPC
向服务器发送RPC命令时，向以下URL发送POST请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/rpc
其中
$ACCESS_TOKEN为设备的access token。
请求体与响应体须为合法JSON。内容由处理该请求的Rule Node决定。
示例
- 在 Root Rule Chain 中添加两个节点：transformation script 和 rpc call reply，并用 “Success” 链接连接到 “Log RPC from Device” action节点。
- 在 script 节点中输入函数：
1
return {msg: {time: new Date()}, metadata: metadata, msgType: msgType};
- 将rpc-client-request.json保存到您的PC；
- 使用下方命令向服务器发送请求：
1
curl -X POST -d @rpc-client-request.json https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"
应收到来自服务器的响应：
1
{"time":"Thursday, February 5, 2026, 9:08:22 AM Coordinated Universal Time"}
设备认领
设备认领功能允许终端用户在设备部署并连接至ThingsBoard后，安全地将设备与自身账号关联。 设备认领流程及支持场景详见 设备认领 文档。
认领请求
发起设备认领时，设备须向以下端点发送POST请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/claim
其中
$ACCESS_TOKEN为设备的access token。
请求体
请求体须包含如下JSON结构：
1
{"secretKey":"value", "durationMs":60000}
字段说明
- secretKey — 用于授权认领流程的密钥
- durationMs — 设备可被认领的时间窗口（毫秒）
注意：以上字段可选。若未指定 secretKey，则默认使用空字符串。 若未指定 durationMs，则使用系统参数 device.claim.duration（位于 /etc/thingsboard/conf/thingsboard.yml 文件）。
设备预配置
设备预配置支持在无需于ThingsBoard UI中手动创建的前提下动态注册设备。 预配置流程及支持场景详见设备预配置文档。
预配置请求 发起设备预配置时，向以下端点发送POST请求：
1
https://eu.thingsboard.cloud/api/v1/provision
请求体
预配置请求须使用如下JSON格式：
1
2
3
4
5
{
"deviceName": "DEVICE_NAME",
"provisionDeviceKey": "u7piawkboq8v32dmcmpp",
"provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}
字段说明
- deviceName — 待预配置的设备名称。
- provisionDeviceKey — 在ThingsBoard中配置的预配置密钥（Provisioning key）。
- provisionDeviceSecret — 与该预配置密钥关联的预配置密文（Provisioning secret）。
若凭据有效，ThingsBoard将自动创建设备（若尚不存在）并返回设备凭据，使设备可与平台通信。
固件API
ThingsBoard通过HTTP发起固件更新时，会设置共享属性 fw_title、fw_version、fw_checksum、fw_checksum_algorithm。
设备要获取固件更新信息并下载固件，须向以下端点发送GET请求：
1
https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION
参数
• $ACCESS_TOKEN 为设备的access token
• $TITLE - 固件标题
• $VERSION - 目标固件版本
协议自定义
可通过修改对应模块针对特定场景对HTTP传输进行全面自定义。