MQTT 采集客户端
插件用途
通过 MQTT Client 订阅并采集消息数据
选择入口
进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“MQTT 采集客户端”。
支持的通道和数据类型
| 通道类型 | 配置前检查 |
|---|---|
| 插件内置连接 | 连接参数在设备动态属性中配置，不使用公共 TCP、UDP 或串口通道参数。 |
可选数据类型： 对象（由协议节点或载荷决定）
插件参数
该插件在设备属性中维护 MQTT 连接，不使用普通 TCP、UDP 或串口通道字段。失败重试、写优先等采集公共运行属性仍按采集配置配置。
连接配置
| 参数 | 说明 |
|---|---|
| 连接类型 | 默认：Tcp；填写：下拉选择。设置建立连接时使用的连接类型。 |
| IP地址 | 默认：localhost；填写：文本输入。设置建立连接时使用的IP地址。 |
| 端口 | 默认：1883；填写：数字输入。设置建立连接时使用的端口。 |
| WebSocket路径 | 默认：/mqtt；填写：文本输入。设置建立连接时使用的WebSocket路径。 |
| 客户端ID | 填写：文本输入。设置建立连接时使用的客户端ID。 |
| 清除会话 | 默认：是；填写：开关。控制“清除会话”功能是否启用。 |
| MQTT协议版本 | 默认：4；填写：下拉选择。设置建立连接时使用的MQTT协议版本。 |
“连接类型”只有 Tcp 和 WebSocket；“MQTT协议版本”选项为 V310（MQTT 3.1）、V311（MQTT 3.1.1）和 V500（MQTT 5.0）。选择 WebSocket 时，实际 URL 为 ws://IP:端口/WebSocket路径；启用 SSL 后为 wss://。
安全认证
| 参数 | 说明 |
|---|---|
| 启用SSL | 默认：否；填写：开关。控制“启用SSL”功能是否启用。 |
| SSL目标主机名 | 填写：文本输入。设置身份校验或安全连接使用的SSL目标主机名。 |
| 客户端证书名称 | 填写：证书选择。设置身份校验或安全连接使用的客户端证书名称。 |
| CA名称 | 填写：证书选择。设置身份校验或安全连接使用的CA名称。 |
| 允许不受信任证书 | 默认：是；填写：开关。控制“允许不受信任证书”功能是否启用。 |
| SSL协议版本 | 默认：0；填写：下拉选择。设置身份校验或安全连接使用的SSL协议版本。 |
| 检查证书吊销 | 默认：否；填写：开关。控制“检查证书吊销”功能是否启用。 |
| 用户名 | 填写：文本输入。设置身份校验或安全连接使用的用户名。 |
| 密码 | 填写：文本输入。设置身份校验或安全连接使用的密码。 |
生产环境应关闭“允许不受信任证书”，并配置“SSL目标主机名”和 CA；启用双向 TLS 时再选择客户端证书。用户名非空时，Broker 返回的认证必须与用户名和密码完全匹配。
运行参数
| 参数 | 说明 |
|---|---|
| 保活时间 | 默认：60；填写：数字输入。设置插件运行时使用的保活时间。 |
| 连接超时时间 | 默认：3000；填写：数字输入。设置建立连接允许等待的最长时间。 |
消息配置
| 参数 | 说明 |
|---|---|
| QoS等级 | 默认：0；填写：下拉选择。设置消息发布或订阅使用的QoS等级。 |
QoS 选项为 0（最多一次）、1（至少一次）和 2（恰好一次），同时用于订阅和插件发出的控制消息。
日志诊断
| 参数 | 说明 |
|---|---|
| 详细日志 | 默认：否；填写：开关。开启后记录更详细的连接、模板或收发日志，排障完成后可关闭以减少日志量。 |
缓存与可靠性
| 参数 | 说明 |
|---|---|
| 检查清除时间 | 默认：60000；填写：数字输入。设置缓存、重试或连接恢复使用的检查清除时间。 |
地址规则
- 变量地址：${订阅主题};${JSONPath1||JSONPath2};${Condition};${发布主题};${Json|RawString};${Retain};${RPC响应主题};${RPC超时毫秒}
- 只读示例：vendor/device;$.data.temperature;TelemetryCondition
- 只写示例：;;;factory/a/reboot;RawString;false
- RPC 示例：;;;factory/a/command/{RequestId};Json;false;factory/a/response/{RequestId};5000
- 负载示例：
- {
- "data": {
- "items": [ { "value": 12.5 } ],
- "temperature": 31
- },
- "a.b": "special",
- "devs": [{ "d": [{ "m": "ZP_AA01_01_VC", "v": 233.4 }] }]
- }
- 示例：vendor/device;$.data.items[0].value，结果是 12.5
- 示例：vendor/device;$['a.b']，结果是 "special"
- 示例：vendor/device;$.devs[0].d[?(@.m == 'ZP_AA01_01_VC')].v，结果是 233.4
- 示例：vendor/device;$.data.temperature||$.payload.temperature;ConditionName
- 路径支持省略根符号 $，数组也可使用 items.0.value；候选路径按从左到右的顺序取第一个存在字段。
- 支持过滤器 [?()]、通配符 [] 与 .、递归下降 $..name；匹配多个节点时按文档顺序取第一个。
- 括号外的 || 分隔候选路径，过滤器 [?()] 内的 || 表示逻辑或。
- 属性先精确匹配大小写；仅当不存在精确名称时，才使用唯一的忽略大小写匹配。
- 条件是 DataTrans 脚本名称，raw 为完整 Payload JSON；可声明 Topic 或 MqttTopic 输入参数读取实际发布主题。
- 通配主题匹配的所有消息会更新同一变量；需要按设备隔离时请配置精确主题，或在条件脚本中按 Topic 过滤。
- MQTT 采集客户端收到的订阅消息不包含发布者客户端 ID，因此 ClientId 和 MqttClientId 输入参数为空。
- 发布主题不能使用 + 或 #；RPC 请求和响应主题的 {RequestId} 必须独占最后一个 Topic 层级。
- 地址最多 8 段；订阅主题与 JSONPath 必须同时填写，发布选项必须依附发布主题。RPC 响应主题和超时必须同时填写，超时范围为
100～60000毫秒。 - 变量为“只读”时不能填写发布字段；变量为“只写”时不能填写订阅和 JSONPath 字段；至少配置一条读取或写入路由。
设备调试
进入“开发配置 → 采集配置”，选择当前设备后点击“更多功能”并打开“调试”。
协议调试 · MqttClient
| 功能 | 作用 |
|---|---|
| 发布消息 | 填写 Topic、Payload、QoS 和 Retain，使用当前 MQTT 连接发布测试消息。 |
| 订阅管理 | 查看当前订阅，新增测试订阅或取消订阅。 |
| 刷新订阅 | 重新读取插件当前实际订阅列表，用于核对变量 Topic 是否生效。 |
调试要点
先用精确 Topic 订阅测试消息，再核对 JSONPath、条件脚本和变量更新时间；通配 Topic 会把匹配消息更新到同一变量。
验证重点
- 确认设备在线，并在“订阅管理”中看到变量配置使用的精确 Topic。
- 从测试发布端向该 Topic 发送一条已知 JSON，例如
{"data":{"temperature":31}}。 - 使用地址
vendor/device;$.data.temperature的测试变量应更新为31，采集时间同步变化且无解析错误。 - 再测试一个不存在的首选 JSONPath 和有效备用 JSONPath，确认
||按从左到右选择第一个存在字段。 - 发布和 RPC 写入只使用测试 Topic；不要向生产控制 Topic 发送试验消息。
排障差异
- 设备无法连接：检查连接类型、Broker 地址和端口、客户端 ID、账号密码、MQTT 版本及 TLS 证书配置。
- 已连接但订阅列表没有变量 Topic：核对变量地址第一段、QoS 和设备是否已重新加载配置。
- 收到消息但变量不更新：检查 JSONPath、Payload 是否为有效 JSON、条件脚本返回值和变量数据类型。
- 通配 Topic 的设备数据互相覆盖：改用精确 Topic，或在条件脚本中按
Topic过滤；客户端无法取得发布者 ClientId。 - RPC 超时：确认请求和响应 Topic 的
{RequestId}独占最后一个层级，并检查对端是否按同一 RequestId 回复。 - 保存失败：按错误提示检查段数、JSONPath、主题通配符、读写权限组合以及 RPC 超时范围。