Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: add example of how to add extra user properties to mqtt action #2781

Merged
merged 3 commits into from
Dec 26, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions en_US/data-integration/data-bridge-mqtt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

:::

Expand Down Expand Up @@ -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:

Expand All @@ -112,11 +112,23 @@ 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 a 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/#'
```

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:

Expand Down Expand Up @@ -186,7 +198,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

Expand Down Expand Up @@ -266,4 +278,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
```

12 changes: 12 additions & 0 deletions zh_CN/data-integration/data-bridge-mqtt.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,18 @@ 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/#'
```

4. 添加动作,从**动作类型**下拉列表中选择 `MQTT 服务`,保持动作下拉框为默认的`创建动作`选项,此处我们创建一个全新的 Sink 并添加到规则中。

5. 在下方的表单中输入 Sink 的名称与描述。
Expand Down
Loading