本页目录

• 数据点
• 时序数据API
• 可视化
• 存储
• 保留
• 持久化
• 规则引擎
• REST API
  • 获取数据键
  • 获取时序数据
  • 获取历史数据
• WebSocket API
  • 实例

ThingsBoard提供了一组与时序列数据相关的功能：

• 采集 基于各种协议和集成采集数据；
• 存储 基于SQL(PostgreSQL)或NoSQL(Cassandra或Timescale)数据库存储时间序列数据；
• 查询 基于API查询最新时序数据或指定时间范围内的所有数据；
• 订阅 基于WebSockets订阅数据进行可视化或实时分析；
• 可视化 基于仪表板和部件可视化时序数据；
• 过滤和分析 基于规则引擎过滤和分析数据；
• 生成 基于采集数据产生警报；
• 转发 基于External规则节点将数据发送到外部系统（例如：Kafka或RabbitMQ规则节点）。

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

数据点

ThingsBoard 将遥测（时序）数据视为带时间戳的键值对，将一个带时间戳的键值对称为数据点，键值对的数据结构具有简单灵活的特点可以无缝与物联网设备集；key始终是一个字符串而值可以是string、boolean、double、integer或者JSON。

以下示例使用内部数据格式设备本身可以使用各种协议和数据格式上传数据，更多详细信息请参见时间序列数据上传API 。

以下数据包含5个数据点： 温度 (double), 湿度 (integer), hvac启用(boolean), hvac状态(string)和配置(JSON)：

1
2
3
4
5
6
7
8
9
10
11
{
 "temperature": 42.2, 
 "humidity": 70,
 "hvacEnabled": true,
 "hvacState": "IDLE",
 "configuration": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

你可能会注意到上面列出的JSON没有时间戳在这种情况下ThingsBoard使用当前服务器时间戳但是你可以在消息中包含时间戳信息。

请参见下面的例：

1
2
3
4
5
6
7
{
  "ts": 1527863043000,
  "values": {
    "temperature": 42.2,
    "humidity": 70
  }
}

时序数据API

你可以使用内置的传输协议：

• MQTT
• CoAP
• HTTP
• LwM2M

上面的数协议都支持JSON、Protobuf或自己的数据格式, 对于其他协议请查看“如何连接设备”指南。

可视化

假设已经将时间序列数据推送到ThingsBoard后你可以在仪表板中进行数据可视化，我们建议你先学习仪表板概述中的相关知识如果你撑握了仪表板和数据源配置之后，就可以使用digital和analog、cards、Charts或entities table可视化历史和实时数据，可以使用maps部件可视化设备和资产的位置。

还可以使用input widgets通过仪表板对时序数据进行修改。

存储

ThingsBoard能够配置遥测（时序）数据存储在SQL(PostgreSQL)或NoSQL(Cassandra或Timescale)数据库中；对于每秒少于5000个数据点的生产环境建议使用SQL存储，如果具有高吞吐和高可用的性能要求时将数据存储在Cassandra中才更有意义。

有关详细信息请参阅SQL vs NoSQL vs Hybrid模式。

保留

数据保留策略和配置取决于选择的存储方式Cassandra通过TTL参数设置数据保留时间可以在thingsboard.conf或者thingsboard.yml文件配置TS_KV_TTL默认值或者在Save Timeseries节点的TTL参数进行默认值覆盖。

TTL的最大允许值为5年例如：你可以将原始数据存储3个月，聚合数据存储3年。

PostgreSQL和Timescale不支持每行的（TTL） 参数因此只能使用’SQL_TTL_*‘环境变量配置定期清理时序数据。

持久化

ThingsBoard使用设备配置为特定的设备设置规则链中采用的消息队列进行遥测（时序）数据接收确认，租户管理可以选择消息队列的处理策略（重复处理或忽略）可以实现对数据持久化的精确控制。

规则引擎

规则引擎 负责处理各种输入的数据和事件。
你可能会在下面的规则引擎中找到属性的使用场景：

生成告警

使用警报规则通过UI配置最常见的警报条件或使用过滤器节点通过自定义JS函数配置更具体的用例。

数据修改

使用message type switch规则节点筛选包含”Post telemetry”请求的消息然后使用transformation规则节点修改特定的消息。

差值计算

使用calculate delta规则节点根据智能电表读数计算电力、水和其他消耗量。

验证数据

使用originator telemetry规则节点使用设备的之前时序数据验证输入的时序数据。

分析数据

使用enrichment处理带有设备、相关资产、客户或租户属性的输入遥测消息，允许根据存储在属性中的设置修改处理逻辑和参数。

聚合数据

使用analytics规则节点聚合多个设备或资产的数据。

可根据多个水表的数据计算建筑物/地区的总用水量。

REST API

ThingsBoard提供了以下REST API来获取实体数据：

注意: API通过Swagger UI文档获得更多详细信息请查阅REST API文档，API向后兼容TB v1.0+通过API调用URL包含”plugin”的主要原因。

获取数据键

通过GET请求地址获取指定entity类型和entity id的所有属性key列表

1
http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/keys/timeseries

1
2
3
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"

1
["gas","temperature"]

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

获取时序数据

通过GET请求地址获取指定entity类型和entity id的所有属性value列表

1
http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/values/timeseries?keys=key1,key2,key3

1
2
3
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"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "gas": [
    {
      "ts": 1479735870786,
      "value": "1"
    }
  ],
  "temperature": [
    {
      "ts": 1479735870786,
      "value": "3"
    }
  ]
}

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

获取历史数据

通过GET请求地址获取指定entity类型和entity id的所有属性历史value列表

1
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

The supported parameters are described below:

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

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

1
2
3
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"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "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连接。

1
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://

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
<!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>