知识就是力量——EMQX Dashboard核心规则编写方法及示例

文章目录

[EMQX Dashboard 规则](#EMQX Dashboard 规则)
[一、规则 SQL 基础语法](#一、规则 SQL 基础语法)
二、典型场景规则示例
- [1. 设备状态告警（消息重发布）](#1. 设备状态告警（消息重发布）)
- [2. 数据持久化（写入数据库）](#2. 数据持久化（写入数据库）)
- [3. 客户端事件处理（连接/断开通知）](#3. 客户端事件处理（连接/断开通知）)
[三、高级功能：JSON 数据转换与数组处理](#三、高级功能：JSON 数据转换与数组处理)
- [1. JSON 数据重组（使用 jq 函数）](#1. JSON 数据重组（使用 jq 函数）)
- [2. 数组数据批量处理（FOREACH 语法）](#2. 数组数据批量处理（FOREACH 语法）)
- 四、调试与优化技巧
[MQTT 规则](#MQTT 规则)
一、动作的基本操作逻辑
二、常见动作类型及操作示例
- [1. 消息重发布（Message Republish）](#1. 消息重发布（Message Republish）)
- [2. 数据持久化（写入数据库）](#2. 数据持久化（写入数据库）)
- [3. 调用 HTTP 服务](#3. 调用 HTTP 服务)
- [4. 发送到消息队列（如 Kafka、RabbitMQ）](#4. 发送到消息队列（如 Kafka、RabbitMQ）)
- [5. 控制台输出（调试用）](#5. 控制台输出（调试用）)
三、动作配置注意事项
[EMQX 连接数据库](#EMQX 连接数据库)
一、准备工作
[二、配置数据库资源（EMQX Dashboard 操作）](#二、配置数据库资源（EMQX Dashboard 操作）)
三、创建规则与数据库动作
四、验证与调试
其他数据库适配说明

EMQX Dashboard 规则

在 EMQX Dashboard 中编写规则需围绕数据来源、处理逻辑、结果去向三个维度，通过 SQL 语法实现。以下是核心规则编写方法及示例：

一、规则 SQL 基础语法

规则基于 SQL 语句定义，核心结构包括：

FROM ：指定数据来源（MQTT 主题、客户端事件等），支持通配符（如 sensor/# 匹配所有 sensor/ 开头的主题）。
SELECT ：提取或转换数据，支持 JSON 字段解析（如 payload.temp 提取 payload 中的 temp 字段）。
WHERE：添加过滤条件（如数值比较、字符串匹配）。

示例 1：基础数据过滤

sql 复制代码

SELECT 
  clientid, 
  payload.temperature AS temp, 
  topic 
FROM "sensor/#" 
WHERE payload.temperature > 30  -- 仅处理温度大于30的消息

二、典型场景规则示例

1. 设备状态告警（消息重发布）

当设备温度超过阈值时，将告警消息转发到指定主题：

sql 复制代码

SELECT 
  clientid, 
  payload.temperature AS temp, 
  now() AS alert_time 
FROM "sensor/temp" 
WHERE temp > 40

动作配置 ：选择「消息重发布」，目标主题设为 alerts/high_temp，Payload 填写 ${temp},${clientid},${alert_time}。

2. 数据持久化（写入数据库）

将设备数据存储到 PostgreSQL 数据库：

sql 复制代码

SELECT 
  clientid, 
  payload.humidity AS hum, 
  payload.temp AS temp, 
  timestamp div 1000 AS ts  -- 时间戳转换为秒
FROM "sensor/telemetry"

动作配置：选择 PostgreSQL 连接器，SQL 模板填写：

sql 复制代码

INSERT INTO sensor_data (client_id, humidity, temperature, time) 
VALUES (${clientid}, ${hum}, ${temp}, TO_TIMESTAMP(${ts}))

3. 客户端事件处理（连接/断开通知）

捕获客户端连接事件并打印到控制台：

sql 复制代码

SELECT 
  clientid, 
  username, 
  connected_at 
FROM "$events/client/connected"

动作配置 ：选择「控制台输出」，输出格式填写 设备 ${clientid}（用户 ${username}）于 ${connected_at} 上线。

三、高级功能：JSON 数据转换与数组处理

1. JSON 数据重组（使用 jq 函数）

将第三方设备的 JSON 格式转换为平台标准格式：

sql 复制代码

SELECT 
  first(jq('{
    "device_id": .devId, 
    "status": "online", 
    "metrics": {
      "temp": .data.temp, 
      "hum": .data.hum
    }
  }', payload)) AS result 
FROM "device/raw" 
WHERE is_not_null(payload.devId)

2. 数组数据批量处理（FOREACH 语法）

当 payload 包含设备数组时，逐个提取并处理：

sql 复制代码

FOREACH 
  payload.devices AS device 
DO 
  device.id AS dev_id, 
  device.status AS status, 
  clientid 
FROM "gateway/batch" 
WHERE device.type = 'sensor'

四、调试与优化技巧

规则测试：在 Dashboard 中启用「调试模式」，输入模拟数据（如 payload、clientid）验证 SQL 逻辑。
性能优化 ：
- 过滤高频冗余数据：WHERE payload.type = 'event' AND timestamp > now() - interval '10s'
- 限制结果字段：仅选择必要字段（如 SELECT clientid, payload.temp FROM ...），减少数据传输开销。

通过以上步骤，可根据业务场景灵活编写 EMQX 规则，实现数据的过滤、转换、转发或存储，满足物联网场景下的各类需求。

MQTT 规则

在 MQTT 规则引擎（如 EMQX、Mosquitto 规则引擎等）中，
动作（Action） 是规则的"执行环节"，用于定义规则匹配后的数据处理方式（如转发消息、存储数据、调用接口等）。动作的配置需与规则的 SQL 逻辑配合，实现数据的流转或持久化。以下是动作的核心操作逻辑、常见类型及配置示例：

一、动作的基本操作逻辑

绑定规则：每个动作必须关联一条规则，当规则的 SQL 筛选出符合条件的数据后，自动触发动作执行。
参数映射 ：动作需引用规则 SQL 中提取的字段（如 ${clientid} ${temp}），将处理后的数据传递到目标载体。
异步执行：多数动作采用异步方式，避免阻塞规则引擎主线程（如数据库写入、HTTP 请求等）。

二、常见动作类型及操作示例

以 EMQX 为例，常用动作包括以下几类，配置步骤大同小异：

1. 消息重发布（Message Republish）

作用：将规则处理后的数据转发到另一个 MQTT 主题（如告警主题、聚合主题）。
配置步骤：

选择动作类型：「消息重发布」。
目标主题：填写转发的目标 MQTT 主题（如 alerts/${clientid}，支持变量引用）。
QoS 等级：根据可靠性需求设置（0/1/2，建议与源消息一致）。
Payload 格式：定义转发的消息内容，支持引用 SQL 字段，例如：
json 复制代码
```
{
  "device": "${clientid}",
  "temp": "${temp}",
  "alert_time": "${alert_time}"
}
```
保留消息（Retain）：按需开启（如静态配置类消息可设为保留）。

2. 数据持久化（写入数据库）

作用：将设备数据存储到数据库（如 MySQL、PostgreSQL、InfluxDB 等）。
前提：需先在"资源"中创建数据库连接器（配置地址、账号、密码等）。
配置步骤：

选择动作类型：例如「MySQL - 插入数据」。
选择资源：关联已创建的数据库连接器。
SQL 模板：编写插入语句，用 ${字段名} 引用 SQL 提取的变量，例如：
sql 复制代码
```
INSERT INTO device_data (device_id, temperature, collect_time)
VALUES (${clientid}, ${temp}, FROM_UNIXTIME(${ts}/1000))
```
（注：时间戳需根据数据库格式转换，如 MySQL 用 FROM_UNIXTIME）。
批量写入（可选）：高频数据场景下，开启批量模式（如累计 100 条或 5 秒批量提交）。

3. 调用 HTTP 服务

作用：将数据推送到外部 API（如业务系统、云平台）。
配置步骤：

选择动作类型：「HTTP 请求」。
请求 URL：填写 API 地址（如 http://api.example.com/device/report）。
请求方法：根据 API 要求选择 GET/POST/PUT 等（POST 常用）。
请求头：设置 Content-Type（如 application/json）、认证信息（如 Authorization: Bearer xxx）。

请求体：用 JSON 格式封装数据，引用 SQL 字段，例如：

json 复制代码

{
  "device_id": "${clientid}",
  "metrics": {
    "temp": "${temp}",
    "hum": "${hum}"
  },
  "timestamp": ${ts}
}

超时设置：建议 5-10 秒，避免长期阻塞。

4. 发送到消息队列（如 Kafka、RabbitMQ）

作用：将数据转发到消息队列，用于高并发场景的异步处理（如大数据分析）。
配置步骤：

选择动作类型：例如「Kafka - 生产消息」。
选择资源：关联已配置的 Kafka 连接器（指定 brokers、topic 等）。
消息键（Key）：可选，用于 Kafka 分区路由（如 ${clientid} 确保同一设备数据入同一分区）。
消息值（Value）：填写发送到 Kafka 的内容，例如 ${payload}（直接转发原始数据）或重组 JSON。

5. 控制台输出（调试用）

作用：规则调试时，将数据打印到服务端控制台，验证逻辑是否正确。
配置步骤：

选择动作类型：「控制台输出」。
输出格式：自定义字符串，引用变量，例如：
设备 ${clientid} 上报温度 ${temp}，时间：${alert_time}

三、动作配置注意事项

变量引用格式 ：不同平台可能有差异，EMQX 用 ${字段名}，其他平台可能用 {``{字段名}}，需按文档规范填写。
错误处理 ：
- 开启"失败重试"：短暂网络故障时，自动重试（建议设置重试次数上限，如 3 次）。
- 配置"死信队列"：多次失败的消息可转发到指定 MQTT 主题（如 action/failed），避免数据丢失。
性能控制 ：
- 高频数据场景下，优先选择批量动作（如批量写入数据库、Kafka 批量发送）。
- 避免在动作中执行耗时操作（如复杂计算），可先通过规则 SQL 预处理数据。

通过合理配置动作，可将 MQTT 消息与外部系统（数据库、API、消息队列等）无缝对接，实现物联网数据的"采集-处理-流转-存储"全链路闭环。如果需要某类动作的详细配置截图或特定平台（如 Mosquitto）的操作示例，可以告诉我具体场景哦~

EMQX 连接数据库

在 EMQX 中连接数据库需通过资源配置 + 规则引擎动作 完成，

以下是详细步骤（以 MySQL 为例）：

一、准备工作

创建数据库与表

先在目标数据库中创建存储 MQTT 数据的表，示例（MySQL）：

sql 复制代码

CREATE DATABASE emqx_rule_engine;
USE emqx_rule_engine;
CREATE TABLE iot_data (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  device_id VARCHAR(255) NOT NULL,
  temperature FLOAT,
  humidity FLOAT,
  collected_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

确保网络连通

确认 EMQX 服务器可访问数据库（如开放 3306 端口，或在同一内网）。

二、配置数据库资源（EMQX Dashboard 操作）

进入 EMQX Dashboard → 规则引擎 → 资源 → 新建资源。
选择数据库类型（如 MySQL ），填写连接参数：
- 服务器地址 ：数据库IP:端口（如 192.168.1.100:3306）。
- 数据库名 ：emqx_rule_engine（需与步骤一的数据库名一致）。
- 用户名/密码：数据库的认证信息。
- 高级配置：可设置连接池大小、超时时间等（默认值通常满足基础需求）。
点击测试连接，验证无误后保存资源。

三、创建规则与数据库动作

进入 规则引擎 → 规则 → 新建规则，编写 SQL 筛选数据：

sql 复制代码

SELECT 
  clientid AS device_id,
  payload.temp AS temperature,
  payload.hum AS humidity,
  timestamp() AS collected_at
FROM "sensor/#"  -- 匹配所有传感器数据主题
WHERE payload.temp > 0  -- 过滤有效数据

添加数据库动作：
- 选择动作类型：数据桥接 → 数据库写入。
- 选择资源：关联步骤二创建的 MySQL 资源。
- 配置 SQL 模板（将规则数据插入数据库表）：
  sql 复制代码
```
INSERT INTO iot_data (device_id, temperature, humidity, collected_at)
VALUES (${device_id}, ${temperature}, ${humidity}, FROM_UNIXTIME(${collected_at}/1000))
```
- 保存规则。

四、验证与调试

使用 MQTT 客户端（如 MQTTX）发布消息到 sensor/temp 主题，示例 payload：
json 复制代码
```
{"temp": 25.5, "hum": 60.2}
```
检查数据库表 iot_data，确认数据已成功写入。

其他数据库适配说明

PostgreSQL ：步骤二选择 PostgreSQL 类型，SQL 模板需适配 PostgreSQL 语法（如时间戳函数 TO_TIMESTAMP）。
InfluxDB（时序数据库）：资源类型选择 InfluxDB，动作需配置 Measurement（相当于表名）和 Tag/Field 映射，适合存储传感器时序数据。
SQLite：本地嵌入式数据库，适合测试场景，资源配置中指定数据库文件路径即可。

通过以上步骤，即可实现 MQTT 数据与数据库的无缝连接，满足物联网场景下的数据持久化、分析等需求。