属性

将自定义属性分配给实体和属性管理

YiCONNECT 提供了将自定义属性分配给您的实体并管理这些属性的能力。这些属性存储在数据库中，可用于数据可视化和数据处理。

属性被视为键值对。键值格式的灵活性和简单性允许与市场上几乎所有物联网设备轻松无缝集成。键始终是一个字符串，基本上是一个属性名称，而属性值可以是字符串、布尔值、双精度值、整数或 JSON。例如：

{
 "firmwareVersion":"v2.3.1", 
 "booleanParameter":true, 
 "doubleParameter":42.0, 
 "longParameter":73, 
 "configuration":{
    "someNumber":42,
    "someArray":[1,2,3],
    "someNestedObject":{"key":"value"}
 }
}

属性名称

作为平台用户，您可以定义任何属性名称。但是，我们建议使用驼峰命名法。这使得编写用于数据处理和可视化的自定义 JS 函数变得很容易。

属性类型

属性分为三种类型。让我们通过示例来回顾一下它们：

服务器端属性

几乎所有平台实体都支持此类属性：设备、资产、客户、租户、用户等。服务器端属性是您可以通过管理 UI 或 REST API 配置的属性。设备固件无法访问服务器端属性。

假设您想要构建一个楼宇监控解决方案并查看几个示例：

1. 纬度、经度和地址是您可以分配给代表建筑物或其他房地产的资产的服务器端属性的良好示例。您可以在仪表板中的地图小部件上使用此属性来可视化建筑物的位置。
2. FloorPlanImage可能包含图像的 URL。您可以使用此属性在图像地图小部件上可视化平面图。
3. maxTemperatureThreshold和tempAlarmEnabled可用于配置和启用/禁用特定设备或资产的警报。

管理界面

• 转到设备。单击特定设备行可打开设备详细信息。选择“属性”选项卡。选择“服务器属性”范围。单击“+”图标。
• 输入新的属性名称。选择属性值类型并输入属性值。
• 使用“最新更新时间”排序可以快速定位新创建的属性。

批量配置功能允许您从 CSV 文件快速创建多个设备和资产及其属性。

REST API

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

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

https://$YOUR_YICONNECT_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SERVER_SCOPE

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

curl -v 'https://demo.yiqisoft.cn/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"}'

类似地，您可以使用以下命令获取所有服务器端属性：

curl -v -X GET 'https://demo.yiqisoft.cn/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”和最新更新的时间戳：

[
    {
        "lastUpdateTs":1617633139380,
        "key":"newAttributeName",
        "value":"newAttributeValue"
    }
]

共享属性

此类属性仅适用于设备。它与服务器端属性类似，但有一个重要区别。设备固件/应用程序可以请求共享属性的值或订阅属性的更新。通过 MQTT 或其他双向通信协议进行通信的设备可以订阅属性更新并实时接收通知。通过HTTP或其他请求-响应通信协议进行通信的设备可以周期性地请求共享属性的值。

共享属性最常见的用例是存储设备设置。让我们假设相同的楼宇监控解决方案并回顾几个示例：

1. targetFirmwareVersion属性可用于存储特定设备的固件版本。
2. 如果房间里太热，maxTemperature属性可用于自动启用 HVAC。

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

管理界面

批量配置功能允许您从 CSV 文件快速创建多个设备和资产及其属性。

REST API

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

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

https://$YOUR_YICONNECT_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SHARED_SCOPE

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

curl -v 'https://demo.yiqisoft.cn/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"}'

类似地，您可以使用以下命令获取所有共享属性：

curl -v -X GET 'https://demo.yiqisoft.cn/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”和最新更新的时间戳：

[
    {
        "lastUpdateTs":1617633139380,
        "key":"newAttributeName",
        "value":"newAttributeValue"
    }
]

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

• 向服务器请求共享属性： MQTT API、CoAP API、HTTP API、LwM2M API；
• 从服务器订阅共享属性更新： MQTT API、CoAP API、HTTP API、LwM2M API；

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

客户端属性

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

客户端属性最常见的用例是报告设备状态。让我们假设相同的楼宇监控解决方案并回顾几个示例：

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

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

通过 REST API 获取客户端属性

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

发送 GET 请求到以下 URL：

https://$YOUR_YICONNECT_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/CLIENT_SCOPE

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

curl -v -X GET 'https://demo.yiqisoft.cn/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”和最新更新的时间戳：

[
    {
        "lastUpdateTs":1617633139380,
        "key":"newAttributeName",
        "value":"newAttributeValue"
    }
]

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

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

属性持久化

YiCONNECT 在 SQL 数据库中存储属性的最新值和最新修改时间。这使得可以在仪表板中使用实体过滤器。由用户发起的对属性的更改记录在审核日志中。

数据查询接口

Telemetry Controller 提供以下 REST API 来获取实体数据：

注意： 上面列出的 API 可通过 Swagger UI 获得。请查看一般REST API文档以了解更多详细信息。

数据可视化

我们假设您已经配置了设备属性。现在您可以在仪表板中使用它们。我们建议使用仪表板概述来开始。一旦您熟悉如何创建仪表板和配置数据源，您就可以使用数字和模拟仪表来可视化温度、速度、压力或其他数值。您还可以使用卡片或实体表来可视化多个属性。

您还可以使用输入小部件来允许仪表板用户更改仪表板上的属性值。

规则引擎

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

根据属性值的逻辑表达式生成警报

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

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

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

对服务器端属性的更改做出反应

使用消息类型切换规则节点过滤包含“属性已更新”通知的消息。然后，使用操作或外部对传入事件做出反应。

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

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

性能提升

您可以通过启用属性缓存来实现更高的性能（请参阅配置属性的cache.attributes.enabled属性）

启用属性缓存后，YiCONNECT 只会从数据库加载特定属性一次，对该属性的所有后续请求都将从更快的缓存连接加载。

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