创建规则

本页主要介绍如何在 EMQX Dashboard 中创建数据处理的规则并为规则添加动作。登录 EMQX Dashboard，点击左侧导航目录中的 集成 -> 规则。然后点击创建按钮，跳转至规则页面。在这里，您可以定义规则的数据源，并确定数据过滤的后续操作，例如重新发布、将结果打印到控制台或通过数据桥接进行转发。

本页面的演示以消息重发布动作作为示例，描述了如何创建一个规则，处理接收到的主题为 t/# 的消息，并消息重新发布到主题 a/1。然而，在添加动作中也描述了“控制台输出”和“使用数据桥接转发”这两类规则动作。

以下步骤演示

定义数据源

在规则页面上，输入规则的名称并添加备注以便未来管理。

在 SQL 编辑器中，您可以自定义语句以添加适合您业务需求的数据源。对于本教程，请保持默认设置，即选择并返回符合 t/# 模式的所有主题下的消息（例如 t/a、t/a/b、t/a/b/c等）。

TIP

本教程假设 payload 是 JSON 格式。

EMQX 内置了丰富的 SQL 语句示例，以帮助您入门。您可以在 SQL 编辑器下点击 SQL 示例按钮进行探索。有关 SQL 语法和用法的更多详细信息，请参阅 SQL 语法与示例。

测试 SQL 语句

这是一个可选步骤，但如果您第一次使用 EMQX 规则，建议进行测试。打开启用调试切换开关，启用 SQL 语句测试。

EMQX 为所有字段提供了默认值，例如数据来源、客户端 ID、用户名、主题、QoS、Payload 等。您只需点击运行测试按钮即可开始测试。如果一切正常，将显示测试通过提示。

SQL 处理结果将以 JSON 形式呈现在输出结果部分。SQL 处理结果中的所有字段都可以通过后续操作（内置操作或数据桥接）以 ${key}的形式进行引用。有关字段的详细说明，请参阅 SQL 数据源和字段。

添加动作

在创建规则页面上，点击页面右侧的添加动作按钮。在展开的添加动作页面上您可以从动作下拉列表中选择三种类型的动作之一：重新发布、控制台输出 和 使用数据桥接转发。

添加消息重发布操作

本节演示了如何将主题为 t/# 的消息重新发布到主题 a/1。在动作下拉菜单中选择消息重发布，然后在点击添加按钮之前，配置以下设置：

• 主题：在本示例中设置为目标主题 a/1；

• QoS：在本示例中设置为重新发布的消息的 QoS 为0；

• Retain：设置是否将此消息作为保留消息转发，本教程中保持默认设置 false；

• Payload：输入 ${payload}，表示重新发布的消息将与原始消息具有相同的 payload，不进行任何修改。

• MQTT 5.0 消息属性：点击切换开关以根据需要配置消息属性，允许您为重新发布的消息添加丰富的消息元数据描述。

  • 有效载荷指示器：指示消息格式。值设置为 false 时，消息是未确定的字节，设置为 true 时，意味着消息体中的有效载荷是 UTF-8 编码的字符数据。这将有助于 MQTT 客户端或 MQTT 服务器可以更加有效的解析消息内容，而不用特意去对于消息体进行格式或类型的判断。
  • 消息过期时间：输入一个值（以秒为单位）以指定消息应在经过一段时间后过期，并且如果未传递给预期的接收方，则被视为无效。
  • 内容类型：指定重新发布消息中的载荷内容的类型或格式（MIME 类型），例如，text/plain 表示文本文件，audio/aac 表示音频文件，而 application/json 表示是一条 JSON 格式的应用消息。
  • 响应主题：输入要将响应消息发布到的特定 MQTT 主题。例如，如果您希望将响应发送到名为"response/my_device"的主题，您应输入：response/my_device。
  • 对比数据：输入一个唯一标识符或数据，以将响应消息与原始请求消息相关联。您可以输入唯一的请求标识符、事务 ID 或在您的应用程序上下文中有意义的任何其他信息。

在创建规则页面，点击底部的创建按钮以完成规则创建。此规则将作为新条目添加到规则页面。您可以查看规则 ID、数据源、启用或禁用规则以及创建时间。您还可以点击设置来修改数据源或添加更多操作，或者点击更多按钮来复制或删除规则。

TIP

重新发布操作不会阻止原始消息的传递。例如，根据规则，主题 t/1下的消息将重新发布到主题 a/1，与此同时，t/1 的消息仍然会传递到订阅了主题 t/1的客户端。

添加控制台输出操作

除了消息重发布操作，您还可以选择将规则的输出打印到控制台以进行调试。

控制台输出操作用于将规则的结果消息打印到控制台或日志文件。

• 如果 EMQX 是通过 emqx console 启动的，则结果将打印到 emqx console 被调用的终端。
• 如果 EMQX 是通过 emqx start 启动的，则结果将打印到 EMQX 的 log 目录下的日志文件（erlang log.*）。

输出格式如下所示：

[rule action] rule_id1
    Action Data: #{key1 => val1}
    Envs: #{key1 => val1, key2 => val2}

其中：

• [rule action] 是重新发布操作被触发的规则 ID。
• Action Data 是规则的输出结果，表示在执行操作时应传递给操作的数据或参数，即您设置消息重发布操作时的 payload 部分。
• Envs 是重新发布时应设置的环境变量，其中可能包含与执行此操作相关的数据源和其他内部信息。

TIP

控制台输出操作仅用于调试。如果在生产环境中使用，可能会导致性能问题。

添加使用数据桥接转发动作

您还可以添加使用数据桥接转发的操作。您只需从数据桥接下拉列表中选择目标数据桥接即可。有关在 EMQX 中创建数据桥接的详细信息，请参阅数据桥接。

测试规则

现在您可以使用 MQTTX 来测试此规则。创建一个客户端，然后使用此客户端订阅主题 a/1并发送一条t/1 的消息。您将在对话框中看到此消息也被重新发布到主题 a/1。

有关如何在 MQTTX 客户端工具和 EMQX 之间建立连接的详细信息，请参阅 MQTTX - 开始使用。

查看规则

EMQX 5.0 引入了 Flows 编辑器，提供了您创建的规则的可视化视图。点击集成 -> Flows 即可访问。该窗口显示您已经为所有遵循 t/# 模式的消息创建了两个规则："rule_4xjx" 将消息发布并将数据流转到 Kafka，而 "rule_z97h" 将消息打印到控制台。

您可以在 Flows 页面或规则页面上点击规则 ID，以查看规则解析的执行和操作统计信息。

注：如果更新规则操作或重新定义数据源，则下面页面中列出的统计信息将重置并重新开始。