功能特性 - 处理遥测数据 - 《Thingsboard 二次开发中文文档》

设备遥测上传 API
遥测服务
- 内部数据存储
  - 数据查询接口
    - 时序数据的键查询接口
    - 时序数据值的查询接口
  - websocket-api
    - 举例
数据可视化
规则引擎

:::info 匹配版本：V3.20
页面状态：已完成
原文地址：点击跳转 :::

ThingsBoard 提供了丰富的与遥测数据相关的功能:

采集基于 MQTT、CoAP 或 HTTP 协议上传的设备数据.
保存将时序数据保存在 Cassandra 中(Cassandra是一个高效、可伸缩和高容错的NoSQL数据库)。
查询查询最新的时序数据值或指定时间间隔内的所有数据。
订阅使用WebSocket订阅数据更新(用于可视化或数据分析)。
可视化 使用可配置和高度可定制的小部件和仪表板可视化时间序列数据。
过滤和分析 使用灵活的规则引擎来过滤和分析数据。
生成警报 根据收集到的数据生成告警。
数据转发 使用规则节点(例如Kafka或RabbitMQ规则节点)将数据转发到外部系统。

本指南大致对上述的特性进行了说明，并提供了一些详细的说明链接。
处理遥测数据 - 图1

设备遥测上传 API

ThingsBoard 提供了一组 API 接口来上传键值对格式(key/value)的时序数据。键值对格式具有灵活、简洁的特性，方便与市场上几乎所有的 IoT 设备轻松无缝地集成。用于遥测数据上传 API 接口只支持特定的网络协议。您可以在相应的参考页面中查看 API 和示例。

MQTT API 参考
CoAP API 参考
HTTP API 参考

遥测服务
遥测服务负责将时序数据存储到内部数据存储; 提供服务器端 API 来查询和订阅数据更新。

内部数据存储
ThingsBoard 使用 Cassandra 非关系型数据库或 SQL 数据库来存储所有数据。
当数据存储到数据库后，服务器会向上传数据的设备发送有关数据传输的确认。现代的 MQTT 客户端允许临时缓存本地未交付的数据。因此，即使其中一个 ThingsBoard 节点宕机，设备也不会丢失数据，并能够将数据推送到其他服务器。
服务器端的程序还能够为不同实体和实体类型推送遥测的值。
尽快你可以直接查询数据库，但 ThingsBoard 提供了一套基于 RESTful 和 Websocket 的 API 接口，它们简化了数据查询过程并加强了数据安全性。
租户管理员能够获取属于自己的所有实体的数据。
客户用户只能获取分配给自己的实体的数据。

数据查询接口
遥测服务提供以下 REST API 来获取实体数据。

注意: 上面列出的 API 可以通过 Swagger UI 获得，请查看通用 REST API 文档了解更多细节。为了 API 能够向下兼容 TB v1.0+ 版本，请求链接中包含了 plugin 字段。

时序数据的键查询接口
你可以用 GET 的请求方式访问以下链接来获取指定实体类型和 id 的所有数据的键的列表
```
http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/keys/timeseries
```
请求命令如下：
```
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"
```
返回的键列表如下
```
["gas","temperature"]
```
支持的实体类型有:租户、客户、用户、仪表板、资产、设备、警报

时序数据值的查询接口
你可以用 GET 的请求方式访问以下链接来获取指定实体类型和 id 的最新的值的列表
```
http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/values/timeseries?keys=key1,key2,key3
```
请求命令如下：
```
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"
```
返回的值列表如下：
```
{
"gas": [
  {
    "ts": 1479735870786,
    "value": "1"
  }
],
"temperature": [
  {
    "ts": 1479735870786,
    "value": "3"
  }
]
}
```
支持的实体类型有:租户、客户、用户、仪表板、资产、设备、警报
还可以使用 GET 请求方式访问以下链接来获取特定实体类型和实体 id 的历史值的列表
```
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 - 用逗号分隔，目标遥测值对应的键的列表。
startTs - unix 时间戳，开始时间，单位：毫秒。
endTs - unix 时间戳，结束时间，单位：毫秒。
interval - 采集间隔(以毫秒为单位)。
agg - 功能集合. 最小值、最大值、平均误差，求和、计数、空。
limit - 要返回或处理的最大数据条数数量。

ThingsBoard 使用 startTs、endTs 和 interval 来标识集合或子查询，并用内置的集合函数对数据库执行异步查询。
请求命令如下：

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"

返回的结果如下：

{
  "gas": [
    {
      "ts": 1479735870786,
      "value": "1"
    },
    {
      "ts": 1479735871857,
      "value": "2"
    }
  ],
  "temperature": [
    {
      "ts": 1479735870786,
      "value": "3"
    },
    {
      "ts": 1479735871857,
      "value": "4"
    }
  ]
}

支持的实体类型有:租户、客户、用户、仪表板、资产、设备、警报

websocket-api

Websockets 被 Thingsobard 广泛的用在Web界面上。Websocket API 复制了 REST API 的功能，并提供了订阅设备数据变化的能力。你可以使用以下链接来建立到遥测服务的 websocket 连接：

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

一旦建立，你可以发送
订阅命令并接收订阅更新:

cmdId - 唯一的命令 id (在相应的 websocket 连接中)
entityType - 唯一的实体类型。支持的实体类型有:租户、客户、用户、仪表板、资产、设备、警报
entityId - 唯一的实体标识符
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://

<!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>
    <a href="javascript:WebSocketAPIExample()">Run WebSocket</a>
  </div>
</body>
</html>

数据可视化

ThingsBoard 支持配置和定制用于数据可视化的仪表板。这些功能会在单独的指南中讨论。
数据可视化指南

规则引擎

ThingsBoard 提供了配置数据处理规则的能力。每个规则由

过滤器 - 过滤筛选传入的数据,
处理器 - 生产警报或者为传入数据填充服务器端的值
执行器 - 将某种逻辑应用于过滤后的数据。你可以在单独的指南中找到更多的细节。

规则引擎指南

处理遥测数据

设备遥测上传 API

遥测服务

内部数据存储

数据查询接口

时序数据的键查询接口

时序数据值的查询接口

websocket-api

举例

数据可视化

规则引擎