马上体验
解决方案
客户
案例
合作伙伴
关于我们
报价 文档 指南

ThingsBoard文档

ThingsBoard平台使用文档。

遥测数据

ThingsBoard提供与遥测数据操作相关的API：

  • 采集 使用MQTT, CoAP或者HTTP协议采集设备数据。
  • 存储 在Cassandra（高效、可扩展、能容错的NoSQL数据库）中存储时序数据。
  • 查询 查询最新时序数据值，或查询特定时间段内的所有数据。
  • 订阅 使用websockets订阅数据更新(用于可视化或实时分析)。
  • 可视化 使用可配置和可配置的小部件以及仪表盘可视化时序数据。
  • 过滤和分析 使用灵活的规则引擎过滤和分析数据(/docs/user-guide/rule-engine/)。
  • 事件警报 根据采集的数据触发事件警报。
  • 数据传输 过规则引擎节点实现与外部数据交互（例如Kafka或RabbitMQ规则节点）。

本指南概述了上面列出的功能以及相关链接，可以获取更多信息。

image

设备遥测上传API

ThingsBoard提供了上传Timeseries的key-value格式API。

key-value的灵活性可以与IoT设备无缝。

遥测上传API基于特定的网络协议。你可以在相应的参考页面中查看API和示例：

遥测服务

遥测服务负责将timeseries数据持久保存至数据库中；提供API进行对数据查询和订阅更新。

数据存储

ThingsBoard使用Cassandra NoSQL数据库或SQL数据库来存储所有数据。

向服务端发送数据的设备将在数据存储在DB中后立即收到有关数据传递的确认。

MQTT客户端允许临时本地存储未交付的数据。

因此即使ThingsBoard节点之一发生故障，该设备也不会丢失数据，并且能够将其推送到其他服务器。

服务端应用程序还能够发布针对不同实体和实体类型有价值的遥测。

虽然你可以直接查询数据库，但是ThingsBoard提供了一组RESTful和Websocket API，可简化调用过程并应用某些安全策略：

  • Tenant管理员能够管理所拥有实体属性。
  • Customer用户只能管理Tenant分配的实体属性。

数据查询API

遥测服务提供以下REST API来获取实体数据:

image

注意: 上图中的API可通过Swagger UI使用，如获取更多详细信息请查看REST API 。 该API向后兼容TB v1.0+，这是API调用URL包含“plugin”的主要原因。

Timeseries数据keys API

你可以使用下面的GET请求地址获取指定entity类型和entity id的所有属性key列表

http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/keys/timeseries
resources/get-telemetry-keys.sh
 
curl -v -X GET http://localhost:8080/api/plugins/telemetry/DEVICE/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/keys/timeseries \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"

支持的实体类型为: TENANT, CUSTOMER, USER, DASHBOARD, ASSET, DEVICE, ALARM, ENTITY_VIEW

Timeseries数据values API

你可以使用下面的GET请求地址获取指定entity类型和entity id的所有属性value列表

http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/values/timeseries?keys=key1,key2,key3
resources/get-latest-telemetry-values.sh
 
curl -v -X GET http://localhost:8080/api/plugins/telemetry/DEVICE/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/values/timeseries?keys=gas,temperature \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/get-latest-telemetry-values-result.json
 
{
  "gas": [
    {
      "ts": 1479735870786,
      "value": "1"
    }
  ],
  "temperature": [
    {
      "ts": 1479735870786,
      "value": "3"
    }
  ]
}

支持的实体类型为: TENANT, CUSTOMER, USER, DASHBOARD, ASSET, DEVICE, ALARM, ENTITY_VIEW

你可以使用下面的GET请求地址获取指定entity类型和entity id的所有属性历史value列表

http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/values/timeseries?keys=key1,key2,key3&startTs=1479735870785&endTs=1479735871858&interval=60000&limit=100&agg=AVG

支持参数如下所述：

  • keys - 以逗号分隔的要获取的遥测key列表。
  • startTs - Unix时间戳标识间隔的开始（以毫秒为单位）。
  • endTs - -Unix时间戳标识间隔的结束时间（以毫秒为单位）。
  • interval - 以毫秒为的聚合间隔单位。
  • agg - 聚合函数。MIN，MAX，AVG，SUM，COUNT，NONE之一。
  • limit - 要返回的最大数据点数或要处理的间隔。

ThingsBoard将使用startTs，endTs和interval来标识聚合分区或子查询，并对利用内置聚合功能的数据库执行异步查询。

resources/get-telemetry-values.sh
 
curl -v -X GET "http://localhost:8080/api/plugins/telemetry/DEVICE/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/values/timeseries?keys=gas,temperature&startTs=1479735870785&endTs=1479735871858&interval=60000&limit=100&agg=AVG" \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/get-telemetry-values-result.json
 
{
  "gas": [
    {
      "ts": 1479735870786,
      "value": "1"
    },
    {
      "ts": 1479735871857,
      "value": "2"
    }
  ],
  "temperature": [
    {
      "ts": 1479735870786,
      "value": "3"
    },
    {
      "ts": 1479735871857,
      "value": "4"
    }
  ]
}

支持的实体类型为: TENANT, CUSTOMER, USER, DASHBOARD, ASSET, DEVICE, ALARM, ENTITY_VIEW

Websocket API

ThingsBoard Web UI使用Websocket API复制了REST API功能，并提供了订阅设备数据更改的功能。

你可以使用以下URL打开与遥测服务的Websocket连接。

ws(s)://host:port/api/ws/plugins/telemetry?token=$JWT_TOKEN

打开后，你可以发送 订阅命令 并接收 订阅更新:

  • cmdId - 命令唯一标识（在相应的Websocket连接中）
  • entityType - 唯一实体类型标识. 支持实类型: TENANT, CUSTOMER, USER, DASHBOARD, ASSET, DEVICE, ALARM
  • entityId - 唯一实体标识符
  • keys - 逗号分隔的keys参数列表
  • timeWindow - 订阅的时间间隔，以毫秒为单位. 数据将在以下时间间隔 [now()-timeWindow, now()]
  • startTs - 获取历史数据查询的间隔的开始时间（以毫秒为单位）.
  • endTs - 获取历史数据查询的间隔的结束时间（以毫秒为单位）.
实例

更改以下变量的值:

  • token - 指向JWT令牌，你可以使用以下链接获得该令牌.

  • entityId - 你的设备ID.

如果是现场演示服务器:

  • 用demo-thingsboard.io替换host:port并选择安全连接-wss://

如果是本地安装:

  • 用127.0.0.1:8080替换host:port并选择ws://
resources/web-socket.html
 
<!DOCTYPE HTML>
<html>
<head>

    <script type="text/javascript">
        function WebSocketAPIExample() {
            var token = "YOUR_JWT_TOKEN";
            var entityId = "YOUR_DEVICE_ID";
            var webSocket = new WebSocket("ws(s)://host:port/api/ws/plugins/telemetry?token=" + token);

            if (entityId === "YOUR_DEVICE_ID") {
                alert("Invalid device id!");
                webSocket.close();
            }

            if (token === "YOUR_JWT_TOKEN") {
                alert("Invalid JWT token!");
                webSocket.close();
            }

            webSocket.onopen = function () {
                var object = {
                    tsSubCmds: [
                        {
                            entityType: "DEVICE",
                            entityId: entityId,
                            scope: "LATEST_TELEMETRY",
                            cmdId: 10
                        }
                    ],
                    historyCmds: [],
                    attrSubCmds: []
                };
                var data = JSON.stringify(object);
                webSocket.send(data);
                alert("Message is sent: " + data);
            };

            webSocket.onmessage = function (event) {
                var received_msg = event.data;
                alert("Message is received: " + received_msg);
            };

            webSocket.onclose = function (event) {
                alert("Connection is closed!");
            };
        }
    </script>

</head>
<body>

<div id="sse">
    <a href="javascript:WebSocketAPIExample()">Run WebSocket</a>
</div>

</body>
</html>

数据可视化

ThingsBoard提供了配置和自定义仪表板以进行数据可视化的功能。点击以下链接了解详情

数据可视化指南

规则引擎

ThingsBoard提供了配置数据处理规则的功能。每个规则包括

  • filters - 过滤传入的数据供稿,
  • processor -生成警报或使用某些服务器端值丰富输入数据
  • action - 对过滤的数据应用某种逻辑. 点击以下链接了解详情

规则引擎指南