事件上报规则

约 2286 字大约 8 分钟

事件上报规则

提示

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

什么是事件上报规则

事件上报规则 是 ThingsCloud 消息规则的一种。当云平台接收到设备端上报的事件消息后，会触发该规则。与属性上报不同，事件通常用于描述设备发生的某次动作或通知，例如按键被按下、设备请求 OTA 升级、告警触发等。

在实际物联网项目中，事件上报规则常用于以下场景：

设备请求 OTA 固件升级检查时，自动返回新版本信息
将设备事件推送到外部 MQTT 服务器或 HTTP 接口
根据当前设备的事件，向其它设备下发属性或命令，实现联动
通过云函数执行自定义处理逻辑

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

提示

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

触发的条件

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

设备已上报事件：设备通过 MQTT、HTTP 等方式，向云平台上报了事件消息。
已创建事件上报规则：在该设备或其所属设备类型下，已创建了事件上报规则。
事件标识符匹配：规则中配置的事件标识符，必须与设备上报事件的事件标识符一致，规则才会触发。

需要特别说明的是：

对于同一设备上报的同一则事件消息，平台仅会触发一条事件上报规则。如果需要同时执行多个操作，需要将它们配置在同一条规则中。
事件上报规则中的操作大多为异步执行，因此操作的先后顺序对运行结果没有直接影响。
在同一条规则内部，同类型操作无论配置多少个，都只会执行一个。

支持的操作

事件上报规则目前支持以下操作：

操作名称	介绍信息
OTA 升级检查	设备请求 OTA 固件升级检查时，自动返回新版本信息。
推送到外部 MQTT	将设备上报的事件消息直接转发到第三方 MQTT 服务器。
推送到外部 URL	将设备上报的事件消息通过 HTTP 请求转发到第三方 URL。
云函数	编写 Javascript 云函数，处理自定义逻辑。

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

操作名称	介绍信息
向其它设备下发属性	向其它指定设备下发属性，实现跨设备联动。
向其它设备下发命令	向其它指定设备下发命令。

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

OTA 升级检查

用于设备 OTA 固件升级时，由设备请求检查固件新版本。详细说明请查看 OTA 固件升级

推送到外部 MQTT

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

提示

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

配置选项

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

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

转发消息示例

假设设备上报了以下事件：

{
    "method": "switchRelay",
    "params": {
        "state1": true,
        "state2": false
    },
    "id": 1000
}

简单格式

发布到 MQTT 主题的消息内容仅包含设备上报的事件内容：

{
    "method": "switchRelay",
    "params": {
        "state1": true,
        "state2": false
    },
    "id": 1000
}

高级格式

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

{
    "device": {
        "id": "string",
        "name": "string",
        "device_key": "string"
    },
    "event": {
        "method": "switchRelay",
        "params": {
            "state1": true,
            "state2": false
        },
        "id": 1000
    },
    "ts": 1704070800123
}

推送到外部 URL

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

提示

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

配置选项

URL 地址：填写第三方接收事件的 URL 地址，当前仅支持 HTTP POST 方式推送。
忽略 SSL 证书校验：当目标 URL 使用 HTTPS 且证书无效或自签名时，打开此开关可忽略 SSL 校验，确保消息正常转发。默认开启。
转发消息格式：选择 HTTP 请求正文的内容格式。
- 简单格式：仅转发设备上报的事件 JSON 内容。
- 高级格式：在事件内容之外，额外包含设备信息、时间戳等元数据。该操作默认使用高级格式。

如果第三方平台只需要原始事件内容，可选择简单格式；如果需要区分设备来源或记录事件上报时间，可选择高级格式。

请求格式

HTTP 请求头

Content-Type: application/json

HTTP 正文

假设设备上报了以下事件：

{
    "method": "switchRelay",
    "params": {
        "state1": true,
        "state2": false
    },
    "id": 1000
}

简单格式

HTTP 正文仅包含设备上报的事件内容：

{
    "method": "switchRelay",
    "params": {
        "state1": true,
        "state2": false
    },
    "id": 1000
}

高级格式

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

{
    "device": {                 // 设备基础信息
        "id": "string",
        "name": "string",
        "device_key": "string"
    },
    "event": {                  // 设备上报的事件
        "method": "switchRelay",
        "params": {
            "state1": true,
            "state2": false
        },
        "id": 1000
    },
    "ts": 1704070800123         // 当前 Unix 时间戳
}

向其它设备下发属性

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

当前设备上报的事件消息，会作为 event 参数传入下发属性的构造函数，您可以编写一定的逻辑，来构造下发到其它设备的属性 attributes。

例如，当前设备上报的事件消息为：

{
    "method": "switchRelay",
    "params": {
        "state1": true,
        "state2": false
    }
}

该操作的属性下发函数，我们这样来写：

module.exports = function (event) {

    var push_attributes = {
        relay1_state: event.params.state1 || false,
        relay2_state: event.params.state2 || false
    };
    return push_attributes;

}