本页目录

• 名称
• 类型
  • 服务端属性
    • 界面
    • REST API
  • 共享属性
    • 界面
    • REST API
    • 设备或应用程序API：
  • 客户端属性
    • REST API
    • 设备或应用程序API：
• 持久化
• 查询接口
• 可视化
• 规则引擎
• 性能提升
• 视频教程

ThingsBoard基于实体提供了自定义属性的功能并保存在数据中库用于可视化和数据处理。

属性是一种key-value格式由于key-value的灵活性可以与IoT设备无缝，键始终是一个字符串而值可以是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"}
 }
}

名称

建议使用骆峰命名方式做为属性名称这样对数据处理和可视化的自定义JS函数十分方便。

类型

属性主要分为三种:

服务端属性

几乎所有平台实体都支持这种类型的属性：Device, Asset, Customer, Tenant, User等；服务器端属性可以通过管理界面或REST API配置的属性，设备固件无法访问服务器端属性。

假设想要构建一个楼宇监控解决方案请查看下面示例：

1. latitude, longitude和address代表建筑物或其他资产的服务器端属性可以在仪表板的地图部件上使用此属性来可视化建筑物的位置。
2. floorPlanImage是图片的URL使用此属性在图片地图部件上可视化平面图。
3. maxTemperatureThreshold和temperatureAlarmEnabled用于配置和启用/禁用设备或资产的警报。

界面

• 添加服务端属性
• 输入属性名称和属性值
• 排序

批量配置可以从CSV文件快速创建多个设备和资产及其属性

REST API

使用REST API文档获取JWT令牌的值将使用它来填充“X-Authorization”标头并验证REST API调用请求。

将带有属性的JSON请求POST发送到以下URL：

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

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

1
2
3
4
curl -v 'https://thingsboard.cloud/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://thingsboard.cloud/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"
    }
]

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

共享属性

共享属性仅适用于设备类似于服务器端属性但区别在于能过订阅更新属性值，通过MQTT或其他双向通信协议可以订阅属性更新并实时接收通知；通过HTTP或其他请求-响应通信协议进行通信的设备可能会定期请求共享属性的值。

假设想要构建一个楼宇监控解决方案请查看下面示例：

1. targetFirmwareVersion属性可用于存储设备的固件版本。
2. maxTemperature属性可用于在房间温过过高时自动启用HVAC。

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

界面

批量配置可以从CSV文件快速创建多个设备和资产及其属性

REST API

使用REST API文档获取JWT令牌的值将使用它来填充“X-Authorization”标头并验证REST API调用请求。

将带有属性的JSON请求POST发送到以下URL：

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

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

1
2
3
4
curl -v 'https://thingsboard.cloud/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://thingsboard.cloud/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"
    }
]

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

设备或应用程序API：

• 从服务器请求共享属性： MQTT, CoAP, HTTP, LwM2M;
• 从服务器订阅共享属性更新：MQTT, CoAP, HTTP, LwM2M;.

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

客户端属性

客户端属性仅适用于设备向服务器上报各种半静态数据与共享属性类似但是区别在设备应用程序将属性值从设备发送平台。

假设想要构建一个楼宇监控解决方案请查看下面示例：

1. currentFirmwareVersion属性可用于向平台报告设备的应用程序版本。
2. currentConfiguration属性可用于向平台报告设备的应用程序配置。
3. currentState可用于通过网络持久保存和恢复设备的应用程序状态。

用户和服务器端应用程序可以通过UI/REST API浏览客户端属性但无法更改它们，因为客户端属性对于UI/REST API是只读状态。

REST API

使用REST API文档获取JWT令牌的值将使用它来填充“X-Authorization”标头并验证REST API调用请求。

将带有属性的JSON请求POST发送到以下URL：

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

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

1
2
3
curl -v -X GET 'https://thingsboard.cloud/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"
    }
]

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

设备或应用程序API：

• 向服务器发布客户端属性：MQTT, CoAP, HTTP;
• 从服务器请求客户端属性：MQTT, CoAP, HTTP.

持久化

ThingsBoard在SQL数据库中存储属性的最新值和最后修改时间可以通过仪表板实体过滤进行数据筛选，用户发起的属性更改记录在审计日志中。

查询接口

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

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

可视化

假设已经配置了设备属性你可以在仪表板中进行数据可视化，我们建议你先学习仪表板概述中的相关知识如果你撑握了仪表板和数据源配置之后，就可以使用digital和analog可视化温度、速度、压力或其它数值又或者用cards或entities table来可视化多个属性。

还可以使用input widgets通过仪表板对属性值进行修改。

规则引擎

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

生成告警

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

数据修改

使用message type switch过滤包含”Post attributes”请求的消息然后使用transformation规则节点来修改特定消息。

属性更新

使用message type switch过滤包含”Attributes Updated”通知的消息然后使用action或external对输入事件做出反应。

分析数据

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

性能提升

可以通过启用属性缓存来实现更高的性能（请参阅属性配置)的cache.attributes.enabled属性）启用后ThingsBoard只会从数据库加载指定的属性，所有对该属性的后续请求将从缓存中加载。

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

视频教程