API / SDK / developer guide
REST API
| 目標讀者 TA | 後端整合者 |
|---|---|
| 官方文件能力 | 管理實體並查詢平台資料。 |
| 輸入 → 輸出 | 授權 REST 請求 → 實體或資料回應。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 現行文件自4.3建議 API key 並棄用 JWT；須符合安裝版本。 |
| 本站建議驗證 | 測試金鑰撤銷與租戶邊界。 |
工業 IoT／SCADA · API / SDK
ThingsBoard REST API
ThingsBoard
透過 REST 接口整合裝置遙測與平台資源。
THINGSBOARD / DEVELOPER FIELD GUIDE
選對接口，定義可驗證的結果。
公司／專案背景、十個技術入口，以及每份引用的實作分析。
2026-10-08 · 串接尚未實測
公司／專案背景全貌
依官方公司或專案自述撰寫的原創概要；完整原文請見來源。
| 產品生態系 | ThingsBoard 提供 IoT 平台軟體及 cloud、edge、gateway 產品。 |
|---|---|
| 整合角色 | 介面連接裝置遙測、狀態、規則與儀表板。 |
| 版本型態邊界 | 本指南使用 Community Edition 文件；須核對部署版本型態功能可用性。 |
| 適用角色 | 進行 AI 供應商初選的採購、合作夥伴與產品負責人。 |
|---|---|
| 本站評估 | 用定位與公司背景判斷初步適配度；另行取得專案部署、支援與商務條件。 |
已核對官方來源。未呼叫供應商 API 或執行推論；結果為內部契約示意。
十項技術入口比較
依實作決策選出的十個技術文件入口，非十套獨立 SDK 或官方排名。
| 接口 | 用途與 TA |
|---|---|
| 01 · REST APIAPI / SDK / developer guide | 管理實體並查詢平台資料。後端整合者 |
| 02 · MQTT connectivityAPI / SDK / developer guide | 透過 MQTT 連接裝置。裝置韌體團隊 |
| 03 · HTTP device APIAPI / SDK / developer guide | 以 HTTP 提交裝置訊息。HTTP 裝置工程師 |
| 04 · Time-series dataAPI / SDK / developer guide | 儲存與查詢具時間戳量測。遙測工程師 |
| 05 · AttributesAPI / SDK / developer guide | 管理作用域最新值屬性。裝置狀態工程師 |
| 06 · Command and controlAPI / SDK / developer guide | 交換裝置命令與回覆。裝置整合團隊 |
| 07 · Rule engineAPI / SDK / developer guide | 路由與轉換輸入訊息。自動化工程師 |
| 08 · AlarmsAPI / SDK / developer guide | 表示異常條件與生命週期。維運設計人員 |
| 09 · Device profilesAPI / SDK / developer guide | 套用共用裝置設定。裝置群管理員 |
| 10 · Gateway APIAPI / SDK / developer guide | 透過閘道表示下游裝置。閘道工程師 |
逐份文件分析
能力摘要依據官方文件；限制與建議測試為本站工程評估。
API / SDK / developer guide
MQTT connectivity
| 目標讀者 TA | 裝置韌體團隊 |
|---|---|
| 官方文件能力 | 透過 MQTT 連接裝置。 |
| 輸入 → 輸出 | 裝置憑證與連線 → 協定工作階段。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 裝置憑證不同於平台 REST 使用者憑證。 |
| 本站建議驗證 | 測試重連與拒絕裝置憑證。 |
API / SDK / developer guide
HTTP device API
| 目標讀者 TA | HTTP 裝置工程師 |
|---|---|
| 官方文件能力 | 以 HTTP 提交裝置訊息。 |
| 輸入 → 輸出 | 授權裝置請求 → 平台確認。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | HTTP 確認不證明下游業務處理完成。 |
| 本站建議驗證 | 讀回預期遙測並檢查失敗。 |
API / SDK / developer guide
Time-series data
| 目標讀者 TA | 遙測工程師 |
|---|---|
| 官方文件能力 | 儲存與查詢具時間戳量測。 |
| 輸入 → 輸出 | 鍵／值／時間 → 歷史讀值。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 時間戳使用 epoch 毫秒；缺少時可由伺服器指定。 |
| 本站建議驗證 | 檢查單位、裝置識別與亂序樣本。 |
API / SDK / developer guide
Attributes
| 目標讀者 TA | 裝置狀態工程師 |
|---|---|
| 官方文件能力 | 管理作用域最新值屬性。 |
| 輸入 → 輸出 | 屬性更新 → 儲存設定／狀態值。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 屬性不是歷史時序儲存。 |
| 本站建議驗證 | 檢查作用域、覆寫行為與讀回。 |
API / SDK / developer guide
Command and control
| 目標讀者 TA | 裝置整合團隊 |
|---|---|
| 官方文件能力 | 交換裝置命令與回覆。 |
| 輸入 → 輸出 | RPC 方法與參數 → 發送狀態或回覆。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 單向200確認發送，不代表裝置執行；雙向要求回覆。 |
| 本站建議驗證 | 對應命令識別並另外驗證實際裝置狀態。 |
API / SDK / developer guide
Rule engine
| 目標讀者 TA | 自動化工程師 |
|---|---|
| 官方文件能力 | 路由與轉換輸入訊息。 |
| 輸入 → 輸出 | 訊息與規則鏈 → 路由動作／結果。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 節點失敗可能阻止預期下游動作。 |
| 本站建議驗證 | 以樣本驗證成功與失敗關係。 |
API / SDK / developer guide
Alarms
| 目標讀者 TA | 維運設計人員 |
|---|---|
| 官方文件能力 | 表示異常條件與生命週期。 |
| 輸入 → 輸出 | 條件評估 → 告警狀態。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 確認收到與清除意義不同。 |
| 本站建議驗證 | 測試建立、確認及恢復清除。 |
API / SDK / developer guide
Device profiles
| 目標讀者 TA | 裝置群管理員 |
|---|---|
| 官方文件能力 | 套用共用裝置設定。 |
| 輸入 → 輸出 | Profile 設定 → 裝置行為預設。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | Profile 變更可能影響多台裝置。 |
| 本站建議驗證 | 全面套用前在代表裝置驗證範圍。 |
API / SDK / developer guide
Gateway API
| 目標讀者 TA | 閘道工程師 |
|---|---|
| 官方文件能力 | 透過閘道表示下游裝置。 |
| 輸入 → 輸出 | 閘道訊息與裝置映射 → 各裝置資料。 |
| 執行環境 | 選定 ThingsBoard 版本／版本型態與授權租戶／裝置連線 |
| 本站選型評估 | 閘道識別不可混合不同下游裝置。 |
| 本站建議驗證 | 檢查映射、斷線與重複裝置名稱。 |
Official documentation
| TA | 工程師與技術產品負責人 |
|---|---|
| 本站驗證建議 | 實作前固定版本並依目標環境核對支援條件。 |
04 / INPUT · EXPECTED OUTPUT · ACCEPTANCE
實作前先看懂預期結果
遙測讀回示意契約；量測值為虛構範例。未連接裝置、寫入遙測或執行 RPC。
示意契約 · 未呼叫 API 或執行模型 · 不是供應商實測輸出
遙測儲存並讀回
| 輸入 | 授權裝置樣本，明確單位與時間戳。 |
|---|---|
| 預期結果 | 比對裝置／鍵／值讀回後 ok。 |
| 驗收條件 | 驗證 epoch 毫秒及設定保留期限。 |
時間窗無資料
| 輸入 | 有效歷史查詢沒有儲存樣本。 |
|---|---|
| 預期結果 | ok 與空量測。 |
| 驗收條件 | 不可用零值替代缺失讀值。 |
命令僅已送出
| 輸入 | 單向 RPC 確認。 |
|---|---|
| 預期結果 | sent 且 execution_verified=false。 |
| 驗收條件 | 宣稱動作完成前需裝置回饋或狀態觀測。 |
憑證已撤銷
| 輸入 | REST key 或裝置憑證遭拒。 |
|---|---|
| 預期結果 | error／denied；無新可信遙測。 |
| 驗收條件 | 維持租戶隔離並遮蔽憑證。 |
將預期結果對應至你的應用
將實際執行環境回應對應至此建議應用契約。所有數值皆為示意，不含憑證或真實執行。
預期輸出 JSON — 示意，非實測 · ThingsBoardAPI-expected-results.json
{
"schema_version": "1.0.0",
"example": true,
"provider": "ThingsBoard",
"status": "ok",
"input_id": "sample-001",
"data": {
"device_id": "example-device",
"measurements": [
{
"key": "temperature",
"value": 23.5,
"unit": "C",
"timestamp_ms": 1791417600000
}
],
"command_execution_verified": false
},
"error": null,
"verification": "illustrative-only;not-provider-response"
}| 狀態語意 | 有效空結果與錯誤不同；等待中的工作不可提前顯示成功。 |
|---|---|
| 證據 | 記錄服務與 SDK 版本、請求識別、設定及回應映射。此處未執行或量測效能。 |
| 建議驗收 | 以授權代表樣本測試前，先約定數值誤差與負載目標。 |
開發評估
設備遙測資料看板
開發構想規格・串接尚未實測
接口能力依據官方文件或程式庫；以下產品方向、輸入、交付與驗收條件則是我們的開發評估。
可先做小原型
確認存取後，用少量真實樣本測試一個有文件的操作。此為開發判斷，不是交期估算。
- 原型輸入規劃
- 測試設備或模擬器、訊號對照表與明確單位。
- 原型交付規劃
- 附時間、資料新鮮度、單位與連線狀態的設備數值。
- 驗收條件
- 對照來源驗證比例與時間；設備斷線時不得顯示正常。
- 依賴條件
- 閘道或服務帳號、設備資料結構與測試環境。
開發順序
- 確認 ThingsBoard REST API 的存取、授權與支援版本。
- 準備上述樣本，針對「設備遙測資料看板」先實作一個有官方文件的操作。
- 整理輸出時保留來源、時間與錯誤狀態，並保留供應商回應供審核。
- 通過驗收條件後，再估算擴展投入與客戶交付。
如何驗證需求
記錄產品瀏覽、官方文件點擊、規格下載與技術 Hub 點擊。這些是事件次數，不等於獨立人數或已完成串接。
本次可行性評估依實作條件判斷；尚未給定流量排名或交期承諾。