属性

• 为实体分配自定义属性及属性管理
• 属性名称
• 属性类型
  • Server-side属性
    • Administration UI
    • REST API
  • 共享属性
    • 设备如何与共享属性交互
    • 通信协议示例
    • Administration UI
    • REST API
    • 设备固件或应用程序的API：
  • 客户端属性
    • 通过REST API获取客户端属性
    • 设备固件或应用程序的API：
• 属性持久化
• 数据查询API
• 数据可视化
• 规则引擎
• 性能优化
• 视频教程

为实体分配自定义属性及属性管理

ThingsBoard支持为实体分配并管理自定义属性。属性存储在数据库中，可用于数据可视化和处理。

属性以key-value形式存储。key-value的灵活性和简洁性便于与IoT设备集成。 key始终为字符串，即属性名；value可为string、boolean、double、integer或JSON。 例如：

1
2
3
4
5
6
7
8
9
10
11
{
 "firmwareVersion": "v2.3.1", 
 "booleanParameter": true, 
 "doubleParameter": 42.0, 
 "longParameter": 73, 
 "configuration": {
    "someNumber": 42,
    "someArray": [1, 2, 3],
    "someNestedObject": { "key": "value" }
 }
}

属性名称

作为平台用户，可自定义任意属性名称。 建议使用camelCase，便于编写数据处理与可视化的自定义JS函数。

属性类型

ThingsBoard支持三种属性类型：server-side（服务端属性）、shared（共享属性）和client-side（客户端属性）。 各类别有各自的用途、访问规则和典型场景，下文分别说明。

Server-side属性

该类型几乎适用于所有平台实体：Device、Asset、Customer、Tenant、User等。 Server-side属性可通过管理界面或RESTAPI配置。 设备固件无法访问server-side属性。

以下是建筑物监测解决方案中的几个服务端属性示例：

1. latitude（纬度）、longitude（经度）和address（地址）是分配给代表建筑物或其他房产的资产的好例子。您可以在仪表盘的地图部件上使用这些属性，可视化建筑物的位置。
2. floorPlanImage可能包含平面图的URL。您可以使用此属性在图像地图部件上可视化楼层平面图。
3. maxTemperatureThreshold（最大温度阈值）和temperatureAlarmEnabled（温度告警启用）可用于配置和启用/禁用特定设备或资产的告警。

Administration UI

• 进入Entities→Devices，点击目标设备行打开详情。在设备详情中打开Attributes选项卡，选择Server attributes作用域，点击"+"添加新属性。
• 在弹窗中输入attribute key，选择value type（如String），并填写value。
• 保存后，新属性会显示在列表中，包含key、value和last update time。可按"Last update time"排序，快速定位新建属性。

Bulk provisioning feature allows you to quickly create multiple devices and assets and their attributes from CSV file.

REST API

参考REST API文档获取JWT令牌的值。您需要用它来填充’X-Authorization’请求头，对您的REST API调用请求进行身份验证。

发送POST请求，将属性的JSON表示发送到以下URL：

1
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SERVER_SCOPE

以下示例为ID为’ad17c410-914c-11eb-af0c-d5862211a5f6’的设备和ThingsBoard Cloud服务器创建名称为”newAttributeName”、值为”newAttributeValue”的属性：

1
2
3
4
curl -v 'https://localhost/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/SERVER_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
--data-raw '{"newAttributeName":"newAttributeValue"}'

同样，您可以使用以下命令获取所有服务端属性：

1
2
3
curl -v -X GET 'https://localhost/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/SERVER_SCOPE' \
  -H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
  -H 'content-type: application/json' 

输出将包含’key’（属性名）、’value’（属性值）和最后更新的时间戳：

1
2
3
4
5
6
7
[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

作为curl的替代方案，您可以使用Java或PythonREST客户端。

共享属性

共享属性仅对设备类型的实体可用，其他实体类型（如资产或客户）不可用。共享属性用于从服务端向设备发送配置或运行参数，例如阈值。

设备如何与共享属性交互

设备无法发布或更改共享属性的值。从设备的角度来看，这些属性是只读的。设备固件或应用程序可以通过以下方式与共享属性交互：

• 请求当前值：设备可以向服务端发送请求，以检索一个或多个共享属性的当前值。
• 订阅更新：设备可以订阅以接收共享属性值在服务端更改时的通知。
• 通过下行消息接收更新：对于某些网络集成，共享属性更新可以作为下行消息被推送到设备。

通信协议示例

接收更新的方法通常取决于设备使用的通信协议：

• 实时订阅（例如MQTT）：使用双向协议（如MQTT）的设备可以订阅属性更新，并在值更改时实时接收通知。
• 周期轮询（例如HTTP）：使用请求-响应协议（如HTTP）的设备可以定期轮询服务端，以获取其共享属性的最新值。

共享属性最常见的用例是存储设备设置。以建筑物监测解决方案为例，共享属性的几个示例如下：

1. targetFirmwareVersion属性可用于存储特定设备的固件版本。
2. 设备可以监测maxTemperatureThreshold属性，当温度超过设定限制时激活冷却系统。

用户可以通过UI更改属性值。脚本或其他服务端应用程序可以通过REST API更改属性值。

Administration UI

• 进入Entities→Devices，点击目标设备行打开详情。在设备详情中打开Attributes选项卡，选择Shared attributes作用域，点击"+"添加新属性。
• 在弹窗中输入attribute key，选择value type（如Double），并填写value。
• 保存后，新属性会显示在列表中，包含key、value和last update time。

Bulk provisioning feature allows you to quickly create multiple devices and assets and their attributes from CSV file.

REST API

参考REST API文档获取JWT令牌的值。您需要用它来填充’X-Authorization’请求头，对您的REST API调用请求进行身份验证。

发送POST请求，将属性的JSON表示发送到以下URL：

1
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SHARED_SCOPE

以下示例为ID为’ad17c410-914c-11eb-af0c-d5862211a5f6’的设备和ThingsBoard Cloud服务器创建名称为”newAttributeName”、值为”newAttributeValue”的属性：

1
2
3
4
curl -v 'https://localhost/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/SHARED_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
--data-raw '{"newAttributeName":"newAttributeValue"}'

同样，您可以使用以下命令获取所有共享属性：

1
2
3
curl -v -X GET 'https://localhost/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/SHARED_SCOPE' \
  -H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
  -H 'content-type: application/json' \

输出将包含’key’（属性名）、’value’（属性值）和最后更新的时间戳：

1
2
3
4
5
6
7
[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

作为curl的替代方案，您可以使用Java或PythonREST客户端。

设备固件或应用程序的API：

• 从服务端请求共享属性：MQTTAPI、CoAPAPI、HTTPAPI、LwM2MAPI；
• 订阅来自服务端的共享属性更新：MQTTAPI、CoAPAPI、HTTPAPI、LwM2MAPI。

如果设备离线，可能会错过重要的属性更新通知。
我们建议在应用程序启动时订阅属性更新，并在每次连接或重新连接后请求属性的最新值。

客户端属性

此类属性仅对设备可用，用于设备（客户端）向ThingsBoard（服务端）报告各种半静态数据。 它类似于共享属性，但有一个重要的区别： 设备固件/应用程序可以将属性值从设备发送到平台。

客户端属性最常见的用例是报告设备状态。以建筑物监测解决方案为例，客户端属性的几个示例如下：

1. currentFirmwareVersion属性可用于向平台报告设备已安装的固件/应用程序版本。
2. currentConfiguration属性可用于向平台报告当前固件/应用程序配置。
3. currentState可用于在设备没有持久化存储时通过网络持久化和恢复当前固件/应用程序状态。

用户和服务端应用程序可以通过UI/REST API浏览客户端属性，但无法更改它们。 基本上，客户端属性的值对于UI/REST API是只读的。

通过REST API获取客户端属性

参考REST API文档获取JWT令牌的值。您需要用它来填充’X-Authorization’请求头，对您的REST API调用请求进行身份验证。

发送GET请求到以下URL：

1
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/CLIENT_SCOPE

以下示例获取ID为’ad17c410-914c-11eb-af0c-d5862211a5f6’的设备和ThingsBoard Cloud服务器的所有属性：

1
2
3
curl -v -X GET 'https://localhost/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/CLIENT_SCOPE' \
  -H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
  -H 'content-type: application/json' \

输出将包含’key’（属性名）、’value’（属性值）和最后更新的时间戳：

1
2
3
4
5
6
7
[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

作为curl的替代方案，您可以使用Java或PythonREST客户端。

设备固件或应用程序的API：

• 向服务端发布客户端属性：MQTT API、CoAP API、HTTP API；
• 从服务端请求客户端属性：MQTT API、CoAP API、HTTP API。

属性持久化

ThingsBoard在SQL数据库中存储属性的最新值和最后修改时间。这使得在仪表盘中能够使用实体过滤器。 用户对属性进行的更改会被记录在审计日志中。

数据查询API

遥测控制器提供以下REST API来获取实体数据：

注意：上述列出的API可通过Swagger UI获取。有关更多详情，请查看REST API文档。 API与ThingsBoard v1.0+向后兼容，这也是API调用URL包含”plugin”的主要原因。

数据可视化

假设您已经配置好设备属性。现在您可以在仪表盘中使用它们。我们建议首先查看仪表盘概览来入门。 一旦您熟悉了如何创建仪表盘和配置数据源， 您可以使用数字和模拟仪表来可视化 温度、速度、压力或其他数值。您也可以使用卡片来可视化多个属性，或使用实体表。

您也可以使用输入部件来允许仪表盘用户更改属性值。

规则引擎

规则引擎负责处理所有传入数据和事件。 下面是在规则引擎中使用属性的最常见场景：

基于属性值的逻辑表达式生成告警

使用告警规则通过UI配置最常见的告警条件， 或使用过滤节点通过自定义JS函数配置更特殊的用例。

在存储到数据库之前修改传入的客户端属性

使用消息类型切换规则节点来过滤包含”Post attributes”请求的消息。 然后使用转换规则节点来修改特定消息。

对服务端属性变更做出响应

使用消息类型切换规则节点来过滤包含”Attributes Updated”通知的消息。 然后使用动作或外部节点对传入事件做出响应。

获取属性值以分析来自设备的传入遥测数据

使用增强规则节点使用设备、相关资产、客户或租户的属性来增强传入的遥测消息。 这是一种非常强大的技术，允许根据存储在属性中的设置修改处理逻辑和参数。

性能优化

启用属性缓存可以实现更高的性能（见配置属性中的 cache.attributes.enabled 配置）。

启用属性缓存后ThingsBoard将只从数据库加载特定属性一次，所有后续属性请求都将从缓存中读取。

注意： 如果您使用Redis或Valkey缓存，请确保将maxmemory-policy更改为allkeys-random，以防止服务填满所有可用内存。

视频教程