From b2f356fe08996696af38bb956b61193c95341f38 Mon Sep 17 00:00:00 2001 From: Thales Macedo Garitezi <16166434+thalesmg@users.noreply.github.com> Date: Wed, 18 Dec 2024 15:50:47 -0300 Subject: [PATCH 1/3] chore: add example of how to add extra user properties to mqtt action --- en_US/data-integration/data-bridge-mqtt.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/en_US/data-integration/data-bridge-mqtt.md b/en_US/data-integration/data-bridge-mqtt.md index a2bb26e58..bf4d70cf5 100644 --- a/en_US/data-integration/data-bridge-mqtt.md +++ b/en_US/data-integration/data-bridge-mqtt.md @@ -47,9 +47,9 @@ Before creating an MQTT Broker data integration, you need to obtain the connecti The data integration provides good compatibility and support for EMQX or other standard MQTT servers. If you need to connect to other types of MQTT services, you can refer to their relevant documentation to obtain the connection information. Generally, most IoT platforms provide standard MQTT access methods, and you can convert device information into the aforementioned MQTT connection information based on their guidance. -:::tip Note +:::tip Note -When EMQX is running in cluster mode or when a connection pool is enabled, using the same client ID to connect multiple nodes to the same MQTT service usually leads to device conflicts. Therefore, the MQTT message bridge currently does not support setting a fixed client ID. +When EMQX is running in cluster mode or when a connection pool is enabled, using the same client ID to connect multiple nodes to the same MQTT service usually leads to device conflicts. Therefore, the MQTT message bridge currently does not support setting a fixed client ID. ::: @@ -101,7 +101,7 @@ This section demonstrates how to create a rule for specifying data to be forward 2. Click **Create** at the top right of the page. -3. Enter the rule ID `my_rule`. +3. Enter the rule ID `my_rule`. 4. In the **SQL Editor**, enter the rule to store MQTT messages from the `t/#` topic to the remote MQTT server. The rule SQL is as follows: @@ -133,6 +133,16 @@ You have now successfully created the rule. You can see the newly created rule o You can also click **Integration** -> **Flow Designer** to view the topology. The topology visually represents how messages under the topic `t/#` are sent to the remote MQTT Broker after being processed by the rule `my_rule`. +Note that, if using MQTTv5 protocol, publish properties are forwarded to the remote broker as is if the `pub_props` field is selected by the rule SQL, as in the `select * from t/#` example from this section. If one wishes to dynamically add more user properties, one can just add then to the `pub_props` field that the rule outputs. For example, the following rule will add an user property with key and value taken from the incoming payload: + +```sql +SELECT + *, + map_put(concat('User-Property.', payload.extra_key), payload.extra_value, pub_props) as pub_props +FROM + 't/#' +``` + ## Test the Rule with MQTT Broker Sink You can use the [MQTTX CLI](https://mqttx.app/zh/cli) to test the Rule for bridging messages published from the `t/#` topic in EMQX to the `pub/${topic}` topic in the external MQTT service. By publishing a message to `t/1` topic in EMQX, the message should be forwarded to the `pub/t/1` topic in the external MQTT service. @@ -186,7 +196,7 @@ This section demonstrates how to create a rule for forwarding data from a remote 8. Configure the Source information to complete the subscription from the external MQTT service to EMQX: - - **Topic**: The subscription topic, supporting the use of `+` and `#` wildcards. + - **Topic**: The subscription topic, supporting the use of `+` and `#` wildcards. ::: tip @@ -266,4 +276,3 @@ You can use [MQTTX CLI](https://mqttx.app/zh/cli) to test the configured rule fo [2024-1-31] [16:49:22] › topic: sub/f/1 payload: I'm from broker.emqx.io ``` - From 703051f62b6c269291bd7aa6043ea5db75f232bb Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Thu, 19 Dec 2024 15:58:49 +0800 Subject: [PATCH 2/3] Edit and add translation --- en_US/data-integration/data-bridge-mqtt.md | 14 ++++++++++++++ zh_CN/data-integration/data-bridge-mqtt.md | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/en_US/data-integration/data-bridge-mqtt.md b/en_US/data-integration/data-bridge-mqtt.md index bf4d70cf5..ddc32fb03 100644 --- a/en_US/data-integration/data-bridge-mqtt.md +++ b/en_US/data-integration/data-bridge-mqtt.md @@ -112,6 +112,20 @@ This section demonstrates how to create a rule for specifying data to be forward "t/#" ``` + If you're using the MQTTv5 protocol, the publish properties are forwarded to the remote broker as-is, provided that the `pub_props` field is included in the rule SQL. This is the case in the `SELECT * FROM t/#` example shown above. + + To dynamically add more user properties, you can include them in the `pub_props` field that the rule outputs. For example, the following rule will add a user property with key and value taken from the incoming payload: + + ```sql + SELECT + *, + map_put(concat('User-Property.', payload.extra_key), payload.extra_value, pub_props) as pub_props + FROM + 't/#' + ``` + + This ensures that custom user properties from the payload are included in the MQTT message sent to the remote broker. + 5. Add an action by selecting `MQTT Broker` from the **Action Type** dropdown list. Keep the **Action** dropdown as the default `Create Action` option. This demonstration creates a new Sink and adds it to the rule. 6. Enter the name and description for the Sink in the form below. diff --git a/zh_CN/data-integration/data-bridge-mqtt.md b/zh_CN/data-integration/data-bridge-mqtt.md index 25cd4f722..26d74fb2a 100644 --- a/zh_CN/data-integration/data-bridge-mqtt.md +++ b/zh_CN/data-integration/data-bridge-mqtt.md @@ -113,6 +113,20 @@ myprefix:foo2bd61c44:1 "t/#" ``` + 如果您使用的是 MQTTv5 协议，只要在规则 SQL 中包含 `pub_props` 字段，发布属性将按原样转发到远程 MQTT 服务器。在上述 `SELECT * FROM t/#` 示例中即是如此。 + + 若要动态添加更多用户属性，您可以将其包含在规则输出的 `pub_props` 字段中。例如，以下规则会从传入的payload 中提取键和值，并添加一个用户属性： + + ```sql + SELECT + *, + map_put(concat('User-Property.', payload.extra_key), payload.extra_value, pub_props) as pub_props + FROM + 't/#' + ``` + + 这确保了来自 payload 的自定义用户属性会被包含在发送到远程 MQTT 服务器的 MQTT 消息中。 + 4. 添加动作，从**动作类型**下拉列表中选择 `MQTT 服务`，保持动作下拉框为默认的`创建动作`选项，此处我们创建一个全新的 Sink 并添加到规则中。 5. 在下方的表单中输入 Sink 的名称与描述。 From f28d39ee7e4bc5b8722f10e9a42ee3ae5ff3dddc Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Fri, 20 Dec 2024 09:13:16 +0800 Subject: [PATCH 3/3] Remove repeated contents --- en_US/data-integration/data-bridge-mqtt.md | 16 ++-------------- zh_CN/data-integration/data-bridge-mqtt.md | 2 -- 2 files changed, 2 insertions(+), 16 deletions(-) diff --git a/en_US/data-integration/data-bridge-mqtt.md b/en_US/data-integration/data-bridge-mqtt.md index ddc32fb03..c61c716ad 100644 --- a/en_US/data-integration/data-bridge-mqtt.md +++ b/en_US/data-integration/data-bridge-mqtt.md @@ -114,7 +114,7 @@ This section demonstrates how to create a rule for specifying data to be forward If you're using the MQTTv5 protocol, the publish properties are forwarded to the remote broker as-is, provided that the `pub_props` field is included in the rule SQL. This is the case in the `SELECT * FROM t/#` example shown above. - To dynamically add more user properties, you can include them in the `pub_props` field that the rule outputs. For example, the following rule will add a user property with key and value taken from the incoming payload: + To dynamically add more user properties, you can include them in the `pub_props` field that the rule outputs. For example, the following rule will add a user property with a key and value taken from the incoming payload: ```sql SELECT @@ -124,13 +124,11 @@ This section demonstrates how to create a rule for specifying data to be forward 't/#' ``` - This ensures that custom user properties from the payload are included in the MQTT message sent to the remote broker. - 5. Add an action by selecting `MQTT Broker` from the **Action Type** dropdown list. Keep the **Action** dropdown as the default `Create Action` option. This demonstration creates a new Sink and adds it to the rule. 6. Enter the name and description for the Sink in the form below. -7. Select the `my_mqtt_bridge` connector you just created from the **Connector** dropdown. You can also create a new connector by clicking the create button next to the dropdown, using the configuration parameters in [Create a Connector](#create-a-connector). +7. Select the `my_mqtt_bridge` connector you just created from the **Connector** dropdown. Alternatively, you can create a new connector by clicking the create button next to the dropdown and using the configuration parameters in [Create a Connector](#create-a-connector). 8. Configure the Sink information for publishing messages from EMQX to the external MQTT service: @@ -147,16 +145,6 @@ You have now successfully created the rule. You can see the newly created rule o You can also click **Integration** -> **Flow Designer** to view the topology. The topology visually represents how messages under the topic `t/#` are sent to the remote MQTT Broker after being processed by the rule `my_rule`. -Note that, if using MQTTv5 protocol, publish properties are forwarded to the remote broker as is if the `pub_props` field is selected by the rule SQL, as in the `select * from t/#` example from this section. If one wishes to dynamically add more user properties, one can just add then to the `pub_props` field that the rule outputs. For example, the following rule will add an user property with key and value taken from the incoming payload: - -```sql -SELECT - *, - map_put(concat('User-Property.', payload.extra_key), payload.extra_value, pub_props) as pub_props -FROM - 't/#' -``` - ## Test the Rule with MQTT Broker Sink You can use the [MQTTX CLI](https://mqttx.app/zh/cli) to test the Rule for bridging messages published from the `t/#` topic in EMQX to the `pub/${topic}` topic in the external MQTT service. By publishing a message to `t/1` topic in EMQX, the message should be forwarded to the `pub/t/1` topic in the external MQTT service. diff --git a/zh_CN/data-integration/data-bridge-mqtt.md b/zh_CN/data-integration/data-bridge-mqtt.md index 26d74fb2a..cd54d7b8c 100644 --- a/zh_CN/data-integration/data-bridge-mqtt.md +++ b/zh_CN/data-integration/data-bridge-mqtt.md @@ -125,8 +125,6 @@ myprefix:foo2bd61c44:1 't/#' ``` - 这确保了来自 payload 的自定义用户属性会被包含在发送到远程 MQTT 服务器的 MQTT 消息中。 - 4. 添加动作，从**动作类型**下拉列表中选择 `MQTT 服务`，保持动作下拉框为默认的`创建动作`选项，此处我们创建一个全新的 Sink 并添加到规则中。 5. 在下方的表单中输入 Sink 的名称与描述。