ThingsBoard REST API完全指南：开发人员必备参考手册-优快云博客

ThingsBoard REST API完全指南：开发人员必备参考手册

【免费下载链接】thingsboard Open-source IoT Platform - Device management, data collection, processing and visualization. 项目地址: https://gitcode.com/GitHub_Trending/th/thingsboard

ThingsBoard作为开源物联网平台（IoT Platform），提供了强大的设备管理、数据采集、处理和可视化能力。其REST API允许开发人员通过HTTP请求与平台交互，实现设备集成、数据查询、告警管理等核心功能。本文将系统介绍API认证机制、核心接口使用方法及最佳实践，帮助开发人员快速上手。

API基础与认证机制

认证流程与令牌管理

ThingsBoard REST API采用JWT（JSON Web Token）认证机制，客户端需通过登录接口获取访问令牌（Access Token）和刷新令牌（Refresh Token）。核心认证逻辑实现于rest-client/src/main/java/org/thingsboard/rest/client/RestClient.java，关键步骤包括：

登录请求：发送用户名/密码至/api/auth/login端点获取令牌对
令牌刷新：当访问令牌过期时，使用刷新令牌调用/api/auth/token端点续期
请求拦截：所有API请求需在HTTP头中携带X-Authorization: Bearer {token}

// 登录示例代码
RestClient client = new RestClient("http://localhost:8080");
client.login("tenant@thingsboard.org", "tenant");
String accessToken = client.getToken();

核心HTTP头与请求格式

Content-Type：支持application/json（默认）和multipart/form-data（文件上传）
分页参数：通过pageSize、page、sortProperty等参数实现结果分页，如?pageSize=10&page=0
时间范围：使用startTime和endTime参数筛选时间序列数据，时间戳格式为毫秒级Unix时间

设备管理API

设备注册与配置

设备管理是IoT平台的核心功能，通过/api/device端点可完成设备的创建、查询与更新。设备实体定义包含名称、类型、状态等属性，完整数据模型参见common/data/src/main/java/org/thingsboard/server/common/data/Device.java。

创建设备示例：

POST /api/tenant/devices
{
  "name": "SmartMeter-001",
  "type": "energy_meter",
  "deviceProfileId": "b89e7c40-1234-5678-90ab-cdef12345678",
  "attributes": {
    "firmwareVersion": "1.2.3",
    "manufacturer": "ABC Corp"
  }
}

设备凭证管理

设备需通过凭证（Credentials）与平台建立安全连接，支持访问令牌、MQTT用户名密码等多种凭证类型。相关接口包括：

获取凭证：GET /api/device/{deviceId}/credentials
更新凭证：POST /api/device/{deviceId}/credentials

凭证类型枚举定义于common/data/src/main/java/org/thingsboard/server/common/data/security/DeviceCredentialsType.java，包含ACCESS_TOKEN、MQTT_BASIC等选项。

数据采集与查询API

遥测数据写入

设备通过/api/v1/{deviceToken}/telemetry端点上报遥测数据，支持单条或批量写入。数据格式支持键值对（KVP）和时序格式，示例：

批量数据上报：

POST /api/v1/DEVICE_TOKEN/telemetry
{
  "temperature": 23.5,
  "humidity": 65,
  "timestamp": 1620000000000
}

历史数据查询

平台提供灵活的时序数据查询接口，支持按实体ID、时间范围和聚合函数筛选数据：

原始数据：GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature,humidity
聚合数据：GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=temperature&agg=NONE&interval=60000

聚合函数（agg）支持AVG、MAX、MIN等，完整列表参见common/data/src/main/java/org/thingsboard/server/common/data/kv/Aggregation.java。

告警与事件管理

告警生命周期管理

ThingsBoard支持告警的创建、更新、确认和清除全生命周期管理。告警实体包含严重性（Severity）、状态（Status）等属性，核心接口实现于rest-client/src/main/java/org/thingsboard/rest/client/RestClient.java的getAlarmById、ackAlarm等方法。

创建告警示例：

POST /api/alarm
{
  "originatorId": "deviceId",
  "originatorType": "DEVICE",
  "type": "high_temperature",
  "severity": "CRITICAL",
  "status": "ACTIVE",
  "details": {
    "currentValue": 85.2,
    "threshold": 80.0
  }
}

告警查询与过滤

通过组合筛选条件可精确查询告警数据，支持按实体、状态、时间范围等维度过滤：

GET /api/alarm?entityType=DEVICE&status=ACTIVE&severity=CRITICAL&startTime=1620000000000&endTime=1620086400000

分页查询结果封装于PageData对象，包含数据列表和分页元信息，定义参见common/data/src/main/java/org/thingsboard/server/common/data/page/PageData.java。

规则引擎与数据处理

规则链管理

规则引擎是ThingsBoard数据处理的核心组件，通过REST API可管理规则链（Rule Chain）的创建与配置。规则链定义包含节点（Node）和连接关系，完整模型参见common/data/src/main/java/org/thingsboard/server/common/data/rule/RuleChain.java。

创建规则链示例：

POST /api/ruleChain
{
  "name": "Temperature Monitoring",
  "firstRuleNodeId": "nodeId",
  "configuration": {
    "processingStrategy": "CHAIN"
  }
}

数据转换与转发

规则节点支持对设备数据进行处理和转发，常用节点类型包括：

脚本节点（Script Node）：使用JavaScript处理数据
外部REST调用节点：将数据转发至第三方服务
保存时序数据节点：存储处理后的遥测数据

节点配置示例可参考rule-engine/rule-engine-components/src/main/java/org/thingsboard/rule/engine/action/TbSendTelemetryActionNode.java。

可视化与仪表板API

仪表板管理

仪表板（Dashboard）是数据可视化的核心载体，支持创建、更新和权限管理。通过API可实现仪表板模板的批量部署，相关接口包括：

创建仪表板：POST /api/dashboard
分配用户：POST /api/dashboard/{dashboardId}/users
获取仪表板信息：GET /api/dashboard/info/{dashboardId}

仪表板数据模型定义于common/data/src/main/java/org/thingsboard/server/common/data/Dashboard.java，包含布局配置、部件（Widget）定义等信息。

部件与数据可视化

部件（Widget）是仪表板的基本组成单元，支持图表、仪表、地图等多种可视化形式。系统提供丰富的内置部件库，自定义部件开发可参考ui-ngx/src/app/modules/dashboard/widgets/目录下的实现。

高级功能与最佳实践

批量操作与性能优化

对于大规模设备管理场景，建议使用批量API减少请求次数：

批量创建设备：POST /api/tenant/devices/batch
批量更新属性：POST /api/plugins/telemetry/attributes/batch

性能优化建议：

使用连接池复用HTTP连接
对频繁查询的数据实施本地缓存
采用分页和过滤减少返回数据量

错误处理与调试

API错误响应格式统一包含status、message和timestamp字段：

{
  "status": 401,
  "message": "Invalid username or password",
  "timestamp": 1620000000000
}

调试工具推荐：

API文档：访问平台/swagger-ui.html查看交互式文档
日志查看：通过docker/logs/目录下的服务日志定位问题
网络抓包：使用Wireshark分析HTTP请求/响应详情

总结与扩展资源

ThingsBoard REST API为物联网应用开发提供了全面的接口支持，从设备接入到数据可视化覆盖了IoT平台的全生命周期。开发人员可通过以下资源深入学习：

官方文档：README.md
API客户端实现：rest-client/
示例代码库：msa/black-box-tests/src/test/java/org/thingsboard/

通过合理利用这些API和工具，开发团队可以快速构建稳定、可扩展的物联网解决方案，实现设备与云端的无缝连接。

【免费下载链接】thingsboard Open-source IoT Platform - Device management, data collection, processing and visualization. 项目地址: https://gitcode.com/GitHub_Trending/th/thingsboard

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考