Skip to content

规则

规则引擎是 EMQX 内置的数据处理功能,它使用 SQL 语句编排规则,并通过消息、客户端事件以及外部数据系统触发,无需编写代码即可实现一站式的 IoT 数据提取、过滤、丰富和转换处理,并将处理完成后的数据输出到动作或外部数据系统中。

规则是构成 EMQX 强大的数据集成能力的一部分,配合使用 Sink/Source 提供了清晰、灵活的业务集成方案,能够简化业务开发流程,提升用户易用性并降低业务系统与 EMQX 的耦合度。详情请查看规则引擎

在左侧的集成菜单下,用户可以进入到规则页面。规则页面中用户可以创建和管理创建好的规则。

创建规则

创建规则可以在规则页面的右上角,点击创建即可进入到创建规则页面。也可以在连接器页面,使用已经创建好的连接器,来快速创建一个规则。

SQL 编辑器

进入到创建规则页面可以看到一个 SQL 编辑器,规则是基于 SQL 语句来使用的,您可以使用 SQL 语句来实时的查询过滤,转换和丰富客户端之间或系统业务之间的数据。顶部两个输入框分别为规则 ID备注,进入创建页面后,会随机生成一个规则 ID 来标识当前规则,也可以手动输入你想要输入的规则标识,可以在备注中输入一些规则的描述信息来区分每个规则的使用。

点击 SQL 编辑器下方的 SQL 示例会在右侧弹出不同的 SQL 模版供您选择以快速创建规则。目前提供了以下比较常用的 SQL 模版:

  • 选择指定主题的消息
  • 同时处理客户端连接、断开连接事件
  • FOREACH 处理 JSON 数组并逐个输出
  • FOREACH 处理 JSON 数组选择指定字段并添加过滤条件
  • CASE-WHEN 从多个条件列表返回可能结果
  • 数组处理 - 从 JSON 格式的 payload 中获取嵌套的值

SQL 语句默认为 SELECT * FROM "t/#",其含义为当客户端向 t/# 这个主题发送消息时,我们就取出当前事件下所有的数据信息。SELECT 关键词可以获取消息中的所有字段,例如可以获取当前消息的 Payload,则 SQL 语句可以修改为 SELECT payload from "t/#",获取的内容可以使用内置函数来进行处理和转化,FROM 关键词后面输入数据源,即事件主题,下方规则调试部分可查看到所有可选的数据源事件,使用 WHERE 关键词,可以添加条件判断,更多详细的 SQL 语法使用,请参考 SQL 语法与示列

启用调试

当完成 SQL 语句的编写后,可以在页面底部的调试区域打开启用调试按钮对 SQL 进行测试。选择触发规则的事件或消息来源,输入模拟的测试数据后,点击 SQL 编辑器下方的运行测试按钮,即可在页面底部的输出结果中看到规则的执行结果。

在每次更改完成 SQL 语句后都可以通过启用调试来测试规则的执行结果,以确保规则的正确性。

TIP

执行 SQL 时如果出现 412 的错误码提示时,可能是与测试数据不匹配造成的,且当数据来源与 SQL 语句不匹配时也会提示选择与其对应的事件或消息来源。更新数据来源事件后,测试数据会自动更新为对应的数据格式

调试时的数据来源与真实使用场景下的一致,包含有一些 MQTT 事件,对于消息部分,我们可以选择不同的消息来源来模拟数据,包括:

  • 消息发布(mqtt topic)
  • 消息投递($events/message_delivered)
  • 消息确认($events/message_acked)
  • 消息丢弃($events/message_dropped)

对于其它事件,我们可以选择不同的客户端和会话事件来模拟数据,包括:

  • 连接完成($events/client_connected)
  • 连接断开($events/client_disconnected)
  • 连接确认($events/client_connack)
  • 鉴权完成($events/client_check_authz_complete)
  • 认证完成($events/client_check_authn_complete)
  • 订阅($events/session_subscribed)
  • 取消订阅($events/session_unsubscribed)

对应的数据源需要与编辑器中的 SQL 语句保持一致,当需要使用上述中的一些消息事件或 Source 来获取数据时,需要将对应的事件主题(括号中的内容)填写到 SQL 语句中, FROM 关键词的后面,规则支持使用多个事件。更多详细的数据源与事件解释,请参考 SQL 数据源和字段

您还可以在调试区域对规则进行测试,详细的测试步骤,参考测试规则

image

动作输出

完成 SQL 语句的编辑和规则调试后,您可以得到一个符合我们需求的输出结果,这时可以在页面右侧的动作输出标签中选择规则触发执行后,需要继续执行的动作。点击添加动作按钮,您可以选择动作来继续处理规则的输出结果。

其中包括以下内置动作:

  • 控制台输出,可以打印结果输出到控制台,可以用于真实场景下的调试。
  • 消息重发布,可以将规则处理后的输出结果,再次发布到指定的主题中。

如果使用外部动作转发数据,可以创建一个新的动作,也可以选择已经创建好的动作。选择动作后,规则的输出结果将转发到对应的外部数据系统上,有关每个动作的配置可参考动作页签。

更多关于规则动作的详情,请参考添加动作

规则列表

当创建完成一个规则后,可以在规则列表中查看到该规则的基本信息,包含规则 ID、规则接入数据的输入(例如事件,主题和 Source 等)、规则的备注、启动状态、规则创建时间, 规则列表中的规则可以进行设置、删除、启用、禁用等操作。点击规则 ID 可以查看规则的详细信息。还可以在更多操作里,选择快速复制一个规则并修改,最大程度提升规则的复用性。

列表顶部包含有一个搜索栏,我们可以使用规则的 ID,接入数据的主题,是否启用和备注来进行多条件的规则查询,帮助用户快速找到符合条件的规则并进行查看和设置等。注意:规则 ID 和备注支持模糊查询,主题支持切换为使用通配符来搜索。

image

规则概览

在规则列表页面,点击规则 ID,可以快速进入规则的概览页面,规则概览页面包含了规则的基本数据统计包括:规则的运行时的统计,当前规则下动作的执行统计。例如规则的命中数,命中并通过的数量,规则的执行速率,失败数,执行动作成功和失败数等。点击右上角的 刷新 可以实时的查看当前规则的运行数据统计。

image

规则设置

点击操作栏设置,可以进入到规则的设置页面,规则设置页面包含了规则的基本信息,设置页面可以进行规则的修改和调试,与创建页面相同。例如需要修改当前规则下的执行动作,修改规则的备注,重新编辑 SQL 语句等。

image