属性上报规则

约 4542 字大约 15 分钟

属性上报规则

提示

如果您还不了解什么是 ThingsCloud 消息规则，以及消息规则的创建方法，请浏览消息规则基础。

什么是属性上报规则

属性上报规则 是 ThingsCloud 消息规则的一种。当云平台接收设备端的属性上报消息，并更新设备属性后，会触发该规则。该规则常用于实现设备联动、数据转发、外部系统集成等业务逻辑。

在实际物联网项目中，属性上报规则的应用场景非常广泛。例如：

根据一个设备上报的温度，自动控制另一个设备的风机开关
设备开机上报时，向设备下发设备码或配置参数
将设备属性转发到第三方 MQTT 服务器或 HTTP 接口
通过网关将数据转发给对应的子设备
执行自定义逻辑，如更新云端私有属性、批量控制多个设备

下图展示了该规则的触发位置：

提示

如果您还不了解 ThingsCloud 设备属性上报的通信规范，请浏览设备属性。

触发的条件

属性上报规则需要同时满足以下条件才会触发：

设备已上报属性：设备通过 MQTT、HTTP 等方式，向云平台上报了属性数据。
已创建属性上报规则：在该设备或其所属设备类型下，已创建了属性上报规则。
满足属性条件（如已设置）：如果规则中设置了属性条件，则上报的属性需要符合该条件，规则才会触发。

需要特别说明的是：

对于同一设备上报的同一则属性消息，平台仅会触发一条属性上报规则。如果需要同时执行多个操作，需要将它们配置在同一条规则中。
在同一条规则内部，不同类型操作会异步执行，且没有严格的先后顺序。
同类型操作无论配置多少个，都只会执行一个。

支持的操作

属性上报规则目前支持以下操作：

操作名称	介绍信息
向当前设备下发属性	向当前上报属性的设备下发属性，实现设备联动。
向当前设备更新云端属性	更新当前设备的云端属性。
向当前设备下发命令	向当前设备下发命令。
向当前设备下发自定义数据	通过自定义数据流，向当前设备下发自定义数据。
推送到外部 MQTT	将设备上报的属性直接转发到第三方 MQTT 服务器。
推送到外部 URL	将设备上报的属性通过 HTTP 请求转发到第三方 URL。
向当前网关上报子设备属性	将属性转发给网关下的子设备，仅用于网关设备。
自定义云函数	编写 Javascript 云函数，处理自定义逻辑。

当属性上报规则直接创建在设备下时，还支持以下操作：

操作名称	介绍信息
向指定设备下发属性	向其它指定设备下发属性，实现跨设备联动。
向指定设备更新云端属性	更新其它指定设备的云端属性。
向指定设备下发命令	向其它指定设备下发命令。
向指定设备下发自定义数据	通过自定义数据流，向其它指定设备下发自定义数据。

在创建或编辑规则时，可以添加这些操作，如下图。

向指定设备下发属性

该操作用于向指定的其它设备下发属性，实现设备联动功能。

选项

选择下发到设备：在这里选择接收平台下发属性的设备。云函数中不需要指定接收的设备。
云函数：动态生成下发属性 JSON 消息。
延迟设置：可设置下发属性的延迟时间（秒数）。

云函数参数

report_attributes：设备上报的属性集合，作为参数传入函数。

云函数返回值

object：构造下发属性 JSON 消息。空的 JSON 对象表示不下发属性。
null：表示不下发属性到设备。

示例：根据温度自动开启风机

例如，当前传感器温度超过30度后，我们希望自动开启风机设备。

我们在操作配置界面中选择要下发的风机设备，假设开关属性为 fan_relay，编写云函数如下：

module.exports = function (report_attributes) {

    var push_attributes = {};
    var temperature = report_attributes.temperature;
    if (temperature !== undefined) {
        // 判断设备是否上报了温度值
        push_attributes.fan_relay = temperature > 30 ? true : false;
    }
    
    return push_attributes;
}

也可以换一种写法，使得在25度到30度之间避免频繁开关，云函数如下：

module.exports = function (report_attributes) {

    var push_attributes = {};
    var temperature = report_attributes.temperature;
    if (temperature !== undefined) {
        if (temperature > 30) {
            // 大于30度时开启风机
            push_attributes.fan_relay = true;
        } else if (temperature < 25) {
            // 小于25度时关闭风机
            push_attributes.fan_relay = false;
        } 
    }

    return push_attributes;
}

示例：为每个设备执行不同的判断

这是一个在智慧农业场景中的例子，我们用到内置函数 Cloud.getCurrentAttributes()，它可以读取设备当前的所有属性值，用于进行各种条件判断。

module.exports = function (report_attributes) {

    // 要下发的属性集合，先空着，如果后边不设置字段，则不会实际下发。
    const push_attributes = {};

    // 获取设备当前的所有属性
    const attrs = Cloud.getCurrentAttributes();

    // 读取上报属性里的光照强度
    const lightIntensity = report_attributes.lightIntensity;

    // 判断是否有上报光照强度，以及设备是否设置为自动模式
    if (lightIntensity !== undefined && attrs.controlMode == "auto") {
        if (lightIntensity < attrs.idealLightIntensity) {
            // 如果当前光照强度低于理想值，打开补光灯
            push_attributes.lightSupplement = true;
        } else {
            // 如果光照强度达到或超过理想值，关闭补光灯
            push_attributes.lightSupplement = false;
        }
    }

    return push_attributes;
}

以上函数中，读取了设备当前属性集合，利用了其中的 controlMode 来判断设备是否处于自动模式，以及 idealLightIntensity 来判断光照亮度是否低于理想值，从而决定是否开启或关闭补光灯。这两个属性都可以通过控制台或用户 App 为设备单独设置，从而实现一个规则对不同设备产生不同的结果。

向当前设备下发属性

该操作用于向当前设备下发属性，实现设备联动功能。

选项

云函数：动态生成下发属性 JSON 消息。
延迟设置：可设置下发属性的延迟时间（秒数）。

云函数参数

report_attributes：是设备上报的属性集合，作为参数传入函数。

云函数返回值

object：构造下发属性 JSON 消息。空的 JSON 对象表示不下发属性。
null：表示不下发属性到设备。

示例：根据开关输入自动控制继电器

例如，我们需要当设备上报开关量 di1 属性变为 ON 后，自动断开继电器 do1，可以编写如下的云函数：

 module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，作为函数参数传入
     * push_attributes:     构造下发的属性对象，作为函数返回值，下发到硬件
     */
    var push_attributes = {

    };

    // 这里的 === 表示上报属性中必须存在 di1 且为 true
    if (report_attributes.di1 === true) {
        push_attributes.do1 = false;
    }
    return push_attributes;
}

示例：设备开机时下发设备码

例如，设备在开机时会上报一个 start_ts 属性，表示设备开机的时间戳。这个属性仅在设备开机时上报一次，非常适合用来触发平台向设备下发设备码。

设备获得设备码后，可在本地显示屏展示，用于用户在 ThingsX 中扫码添加设备。

module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，作为函数参数传入
     * push_attributes:     构造下发的属性对象，作为函数返回值，下发到硬件
     */
    var push_attributes = {};

    // 判断设备是否上报了开机时间戳，仅在开机时下发设备码
    if (report_attributes.start_ts !== undefined) {
        // 获取当前设备信息
        var device_info = Cloud.getDeviceInfo();
        // 将设备码下发给设备
        push_attributes.device_code = device_info.device_code;
    }

    return push_attributes;
}

以上云函数中，通过判断 report_attributes.start_ts 是否存在，来识别设备是否处于开机状态。当设备开机上报该属性时，调用 Cloud.getDeviceInfo() 读取当前设备的详细信息，并将 device_code（设备码）赋值给下发属性。这样可确保设备码仅在开机时下发一次，避免设备在后续正常运行中频繁接收该属性。

关于 Cloud.getDeviceInfo() 的更多说明，请浏览云函数内置函数库。

更多示例可参考 向指定设备下发属性，它们在云函数生成下发属性的部分是完全相同的。

向指定设备下发命令

该操作用于向其它设备下发命令，实现设备联动功能。

选项

选择下发到设备：在这里选择接收平台下发命令的设备。云函数中不需要指定接收的设备。
云函数：动态生成下发命令 JSON 消息。
延迟设置：可设置下发命令的延迟时间（秒数）。

云函数参数

report_attributes：是设备上报的属性集合，作为参数传入函数。

云函数返回值

object 类型：构造一个下发到目标设备的命令 JSON 消息。空的 JSON 对象表示不下发命令。
null：表示不下发命令到设备。

提示

关于下发命令的消息结构说明，请浏览设备接收云端下发命令

示例：根据上报温度自动控制继电器

例如，我们想根据传感器设备上报的温度，来自动执行继电器操作：

当温度升到 35 度或以上，将继电器 #1、#2、#3、#4 开启一次，并在 60 秒后关闭。
当温度降到 27 度或以下，将继电器 #5、#6、#7、#8 开启一次，并在 60 秒后关闭。

本示例为了演示命令下发控制的方式，使用 ThingsEdge DTU 来连接 RS485 继电器，支持下发开关量控制命令。

规则操作中的云函数可以编写如下：

module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，作为函数参数传入
     * command:             构造下发的命令对象，作为函数返回值，下发到硬件
     */
    var command = {}
    // 获得设备上一次的属性
    const attrs = Cloud.getCurrentAttributes();
    
    if (report_attributes.temperature >= 35 && attrs.temperature < 35) {
        // 如果当前温度大于等于 35 度，并且上一次小于 35 度
        command = {
            "method": "switch_relay",
            "params": {
                "attributes": ["relay1", "relay2", "relay3", "relay4"],
                "state": true,
                "delay_reverse": 60     // 60秒后反转
            },
            "id": 1000
        }
    } else if (report_attributes.temperature <= 27 && attrs.temperature > 27) {
        // 如果当前温度小于等于 27 度，并且上一次大于 27 度
        command = {
            "method": "switch_relay",
            "params": {
                "attributes": ["relay5", "relay6", "relay7", "relay8"], // 自己修改这里
                "state": true,
                "delay_reverse": 60     // 60秒后反转
            },
            "id": 1000
        }
    }

    return command;
}

向当前设备下发命令

该操作用于向当前设备下发命令，实现设备联动功能。

选项

云函数：动态生成下发命令 JSON 消息。
延迟设置：可设置下发命令的延迟时间（秒数）。

云函数参数

report_attributes：是设备上报的属性集合，作为参数传入函数。

云函数返回值

object 类型：构造一个下发到目标设备的命令 JSON 消息。
null：表示不下发命令到设备。

提示

关于下发命令的消息结构说明，请浏览设备接收云端下发命令

选择下发到设备：在这里选择接收平台下发自定义数据的设备。云函数中不需要指定接收的设备。
云函数：动态生成下发自定义数据。
延迟设置：可设置下发自定义数据的延迟时间（秒数）。

云函数参数

report_attributes：是设备上报的属性集合，作为参数传入函数。

云函数返回值

object 类型：构造一个下发到目标设备的自定义数据消息。
null：表示不下发数据到目标设备。

向当前设备下发自定义数据

该操作用于向当前设备下发自定义数据，通过目标设备支持的自定义数据流，可下发十六进制、文本、JSON 等格式。

选项

云函数：动态生成下发自定义数据。
延迟设置：可设置下发自定义数据的延迟时间（秒数）。

云函数参数

report_attributes：是设备上报的属性集合，作为参数传入函数。

云函数返回值

object 类型：构造一个下发到目标设备的自定义数据消息。
null：表示不下发数据到目标设备。

推送到外部 MQTT

该操作将设备上报的属性直接转发到第三方 MQTT 服务器，需要填写 MQTT 服务器地址、端口、身份验证信息以及发布主题等。

提示

推送到外部 MQTT 和推送到外部 URL 属于高级功能，需要项目为有效付费版才能使用。

配置选项

MQTT 服务器主机名/IP：填写第三方 MQTT 服务器的域名或 IP 地址。
MQTT 服务器端口：填写 MQTT 服务器的连接端口，例如 1883。
client ID：填写连接 MQTT 服务器时使用的客户端标识符，可自定义，确保在服务器端唯一即可。
username：填写连接 MQTT 服务器时的用户名，用于身份验证。
password：填写连接 MQTT 服务器时的密码，用于身份验证。
发布主题 Topic：填写消息发布到第三方 MQTT 服务器的主题。
转发消息格式：选择转发消息的内容格式。
- 简单格式：仅转发设备上报的属性 JSON 内容。
- 高级格式：在属性内容之外，额外包含设备信息、时间戳等元数据。该操作默认使用高级格式。

根据第三方系统的接入要求，选择合适的转发消息格式。如果接收方只需要原始属性数据，可选择简单格式；如果需要区分设备来源或记录上报时间，可选择高级格式。

转发消息示例

假设设备上报了以下属性：

{
    "temperature": 26.1,
    "humidity": 65
}

简单格式

发布到 MQTT 主题的消息内容仅包含设备上报的属性集合：

{
    "temperature": 26.1,
    "humidity": 65
}

高级格式

发布到 MQTT 主题的消息内容在属性之外，还包含设备基础信息和上报时间戳：

{
    "device": {
        "id": "string",
        "name": "string",
        "device_key": "string"
    },
    "attributes": {
        "temperature": 26.1,
        "humidity": 65
    },
    "ts": 1704070800123
}

推送到外部 URL

该操作将设备上报的属性，通过 HTTP 请求转发到您设置的第三方 URL。

提示

推送到外部 MQTT 和推送到外部 URL 属于高级功能，需要项目为有效付费版才能使用。

配置选项

推送 URL：填写接收推送消息的第三方 HTTP 接口地址。
转发消息格式：选择推送的消息内容格式。
- 简单格式：仅转发设备上报的属性 JSON 内容。
- 高级格式：在属性内容之外，额外包含设备信息、时间戳等元数据。该操作默认使用高级格式。
忽略 SSL 证书校验：当推送 URL 使用自签名证书或证书链不完整时，可开启此选项，避免 SSL 握手失败。

请求格式

平台将以 POST 请求向设置的 URL 推送数据，请求头如下：

Content-Type: application/json

简单格式

HTTP 正文仅包含设备上报的属性集合：

{
    "temperature": 26.1,
    "humidity": 65
}

高级格式

HTTP 正文在属性之外，还包含设备基础信息和上报时间戳：

{
    "device": {
        "id": "string",
        "name": "string",
        "device_key": "string"
    },
    "attributes": {
        "temperature": 26.1,
        "humidity": 65
    },
    "ts": 1704070800123
}

向当前网关上报子设备属性

该操作将设备上报的属性转发到子设备，仅用于当前设备是网关类型的情况下。

选项

云函数：动态生成向网关上报子设备属性的消息。

参数

report_attributes：是设备上报的属性集合，作为参数传入函数。

返回值

object 类型：构造一个向网关上报子设备的消息，消息格式请参考上报子设备属性。
null：表示不转发消息到子设备。

示例

module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，作为函数参数传入
     */

    var data = {};
    if (report_attributes.devEUI) {
        data[report_attributes.devEUI] = report_attributes;
    }

    return data;
}

以上云函数示例的详细介绍请浏览星纵 LoRaWAN UG65 网关使用消息规则转发数据到子设备。

自定义云函数

自定义云函数 操作可处理自定义逻辑，并支持一些内置函数，例如：

更新设备云端私有属性
给指定设备下发属性
给指定设备下发命令