MQTT 采集客户端
通过 MQTT Client 订阅并采集消息数据
选择入口
进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“MQTT 采集客户端”。
支持的通道和数据类型
| 通道类型 | 配置前检查 |
|---|---|
| 插件内置连接 | 连接参数在设备动态属性中配置，不使用公共 TCP、UDP 或串口通道参数。 |
变量类型按当前编辑器选择；使用 Object 时保留载荷字段的对象值，数值、布尔和字符串则按实际字段类型核对。类型设置不会把非 JSON 文本自动变成 JSON。
插件参数
该插件在设备属性中维护 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://。
WebSocket 路径为空时使用 /mqtt，不以 / 开头时会补上斜杠；该路径必须由 Broker 实际提供。TCP 方式不使用路径。客户端 ID 为空时会生成随机身份，重建连接实例后可能改变；需要持久会话或 Broker 按 ID 授权时应填写唯一、稳定的 ID。
优先选择双方实际支持的 V311 或 V500。Unknown 不是正式协议版本；当前 V310 连接的协议名与 MQTT 3.1 标准要求存在差异，不能仅凭下拉选项认定已兼容。修改版本后用新连接和新消息确认，不以旧采集值判断成功。
安全认证
| 参数 | 说明 |
|---|---|
| 启用SSL | 默认：否；填写：开关。控制“启用SSL”功能是否启用。 |
| SSL目标主机名 | 填写：文本输入。设置身份校验或安全连接使用的SSL目标主机名。 |
| 客户端证书名称 | 填写：证书选择。设置身份校验或安全连接使用的客户端证书名称。 |
| CA名称 | 填写：证书选择。设置身份校验或安全连接使用的CA名称。 |
| 允许不受信任证书 | 默认：是；填写：开关。控制“允许不受信任证书”功能是否启用。 |
| SSL协议版本 | 默认：0；填写：下拉选择。设置身份校验或安全连接使用的SSL协议版本。 |
| 检查证书吊销 | 默认：否；填写：开关。控制“检查证书吊销”功能是否启用。 |
| 用户名 | 填写：文本输入。设置身份校验或安全连接使用的用户名。 |
| 密码 | 填写：文本输入。设置身份校验或安全连接使用的密码。 |
生产环境应关闭“允许不受信任证书”，并配置“SSL目标主机名”和 CA；启用双向 TLS 时再选择客户端证书。用户名和密码用于向 Broker 认证，必须与 Broker 为该客户端配置的凭据和权限一致。
SSL 协议版本 None 表示由系统协商，启用 SSL 后仍是加密连接。明确使用 TLS 1.2/1.3 时还需两端及操作系统支持。服务器身份、CA 信任和客户端证书分别配置；吊销检查依赖证书状态服务，关闭它也不等于关闭证书链和主机名校验。
运行参数
| 参数 | 说明 |
|---|---|
| 保活时间 | 默认 60 秒，用于 MQTT 会话保活，不表示遥测每 60 秒更新一次。 |
| 连接超时时间 | 默认 3000。当前 MQTT 采集客户端连接路径未使用该字段调整握手预算；不要据此承诺固定的连接失败时间。结合实际连接日志判断。 |
消息配置
| 参数 | 说明 |
|---|---|
| QoS等级 | 默认：0；填写：下拉选择。设置消息发布或订阅使用的QoS等级。 |
QoS 选项为 0（最多一次）、1（至少一次）和 2（恰好一次），同时用于订阅和插件发出的控制消息。
当前客户端会把订阅返回码 2 判为失败，可能出现 Broker 接受 QoS 2、消息也到达，而订阅确认列表缺失的情况，并影响 RPC 就绪检查。需要完整确认链路时先使用 QoS 1，并由业务接收端处理可能的重复。QoS 确认只覆盖协议交付，不能代替设备执行回执。
日志诊断
| 参数 | 说明 |
|---|---|
| 详细日志 | 默认：否；填写：开关。开启后记录更详细的连接、模板或收发日志，排障完成后可关闭以减少日志量。 |
缓存与可靠性
| 参数 | 说明 |
|---|---|
| 检查清除时间 | 默认 60000，单位为秒。订阅变量距上次采集超过该窗口后转为离线；它不是清理磁盘缓存的周期。 |
地址规则
先接收一个新值
- 配置 Broker 的连接方式、地址、端口和身份，保存启用设备。
- 在设备下新增只读变量，地址填
SubscribeTopic=telemetry/line1;Path=$.data.value;，先使用一个精确 Topic。 - 用独立发布端向
telemetry/line1发送下列 JSON，确认变量得到31、采集时间更新且质量在线。
{"data":{"value":31}}
- 再发送另一个数值，确认持续更新。随后再加入通配 Topic、候选路径或条件脚本，每次只改变一项。
+ 匹配一个主题层级，末级 # 匹配多层范围；它们不负责从消息正文创建多个变量。通配主题与 JSONPath 通配路径属于不同层次。
命名地址
地址使用 属性名称=值;，属性顺序不限，名称不区分大小写，未使用的属性直接省略。最后一个分号可省略，不要重复填写同一属性或混入位置段。
SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;
| 属性名称 | 说明 |
|---|---|
SubscribeTopic | 读取消息的订阅 Topic，可使用 MQTT 主题通配符；与 Path 一起填写。 |
Path | 从有效 JSON 正文中提取字段；多个候选路径用 || 分隔。 |
Condition | 可选 DataTrans 脚本名，返回真才接受该消息。脚本须先创建并编译。 |
ConditionParameters | 可选条件脚本输入参数，填写“参数名到参数文本”的 JSON 对象，各值均为字符串，例如 {"Minimum":"12.5"}。 |
PublishTopic | 写入或 RPC 的目标 Topic；只读变量不填写。 |
PayloadMode | Json 按实际 JSON 类型发送，RawString 发送字符串原文；省略时为 Json。 |
Retain | 写入消息的保留标志，填写 true 或 false；省略时为 false，实际保留能力由 Broker 决定。 |
ResponseTopic | RPC 响应主题，与请求使用相同的 {RequestId}；普通发布可省略。 |
Timeout | RPC 超时，单位毫秒，范围 100～60000；与 ResponseTopic 一起填写。 |
同一读取地址也可写成 Path=$.data.temperature;SubscribeTopic=vendor/device;。只写和 RPC 示例分别为：
PublishTopic=factory/a/reboot;PayloadMode=RawString;Retain=false;
PublishTopic=factory/a/command/{RequestId};PayloadMode=Json;Retain=false;ResponseTopic=factory/a/response/{RequestId};Timeout=5000;
在 Web 编辑器配置条件参数
- 打开变量编辑窗口，点击“变量地址”右侧的“字段编辑”。
- 在“遥测读取”中填写订阅主题和 JSONPath，勾选“条件脚本”并选择已编译的 DataTrans 脚本。
- 根据显示的参数名称、类型和说明逐项输入，无需拼接参数或记忆顺序。
- 点击“确认并回填”应用地址，再保存变量。修改旧地址的字段后应用时，编辑器会生成命名格式；仅查看或取消不会改写地址。
例如脚本声明了数值输入 Minimum，设置为 12.5 后生成：
SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;ConditionParameters={"Minimum":"12.5"}
输入框中的参数文本先按 JSON 值解析，解析失败时作为字符串，再按脚本声明的类型转换。数值可填 12.5，布尔可填 true，对象和数组填写 JSON；字符串通常直接填写，若要保留 true、null 或数字形式的字符串，请输入带双引号的 JSON 字符串，例如 "true"。错误类型或未知参数会阻止保存。
清空参数表示沿用脚本默认值；Topic、MqttTopic、ClientId、MqttClientId 未显式填写时自动注入消息上下文。客户端插件无法取得发布者 ClientId，对应输入为空。每个变量的参数独立保存，同一脚本可以配置不同阈值。
值只按第一个 = 分隔，JSONPath 过滤器中的 == 可以原样填写。命名地址中，值里的分号写为 %3B，百分号写为 %25，编码仅解码一次；Web 编辑器自动处理。例如参数字符串 a;b% 可写成 ConditionParameters={"Marker":"a%3Bb%25"}。地址中的 + 保持原义。
原八段地址
原八段位置格式继续支持，未使用的中间段保留为空，末尾空段可以省略。现有地址无需修改；新增参数请使用命名格式或 Web 编辑器。
订阅主题;JSONPath1||JSONPath2;条件脚本;发布主题;Json或RawString;Retain;RPC响应主题;RPC超时毫秒
vendor/device;$.data.temperature;TelemetryCondition
;;;factory/a/command/{RequestId};Json;false;factory/a/response/{RequestId};5000
下面的 JSON 可用于核对不同路径。采集映射要求有效 JSON；RawString 是发布模式，不能用于读取任意非 JSON 报文。
{
"data": {
"items": [{ "value": 12.5 }],
"temperature": 31
},
"a.b": "special",
"devs": [{ "d": [{ "m": "ZP_AA01_01_VC", "v": 233.4 }] }]
}
SubscribeTopic=vendor/device;Path=$.data.items[0].value;得到12.5。SubscribeTopic=vendor/device;Path=$['a.b'];得到字符串special。SubscribeTopic=vendor/device;Path=$.devs[0].d[?(@.m == 'ZP_AA01_01_VC')].v;得到233.4。SubscribeTopic=vendor/device;Path=$.data.temperature||$.payload.temperature;Condition=ConditionName;先查第一个路径；条件脚本须已创建。- 路径支持省略根符号 $，数组也可使用 items.0.value；候选路径按从左到右的顺序取第一个存在字段。
- 支持过滤器 [?()]、通配符 [] 与 .、递归下降 $..name；匹配多个节点时按文档顺序取第一个。
- 括号外的 || 分隔候选路径，过滤器 [?()] 内的 || 表示逻辑或。
- 属性先精确匹配大小写；仅当不存在精确名称时，才使用唯一的忽略大小写匹配。
- 条件是 DataTrans 脚本名称，raw 为完整 Payload JSON；可声明 Topic 或 MqttTopic 输入参数读取实际发布主题。
- 通配主题匹配的所有消息会更新同一变量；需要按设备隔离时请配置精确主题，或在条件脚本中按 Topic 过滤。
- MQTT 采集客户端收到的订阅消息不包含发布者客户端 ID，因此 ClientId 和 MqttClientId 输入参数为空。
- 发布主题不能使用 + 或 #；RPC 请求和响应主题的 {RequestId} 必须独占最后一个 Topic 层级。
- 订阅主题与 JSONPath 必须同时填写，发布选项必须依附发布主题。RPC 响应主题和超时必须同时填写，超时范围为
100～60000毫秒。 - 变量为“只读”时不能填写发布字段；变量为“只写”时不能填写订阅和 JSONPath 字段；至少配置一条读取或写入路由。
候选路径以“字段是否存在”决定顺序；左侧字段存在但为 null 时，不保证继续取右侧。多个匹配值只取第一个，不会自动扩展为一组采集点。工程路径应与正文大小写一致，以免来源新增同名字段后产生歧义。
发送控制与等待反馈
| 配置 | 操作与结果 |
|---|---|
Json 载荷 | 按实际类型发送 JSON，字符串与对象的线上结构不同。用独立订阅器检查原始正文。 |
RawString 载荷 | 仅接受字符串，发送无 JSON 包装的原文；不能直接写入数值、对象或数组并期待自动转成文本。 |
| Retain | 开启时保存 Broker 上该主题的最后一条消息，新订阅者可能再次收到；不保存历史，也不证明命令执行。之后改为 false 发布不会删除旧保留消息；验证关闭效果时使用新测试主题或先按 Broker 管理方式清理旧保留。 |
| 只写变量 | 省略 SubscribeTopic、Path 和条件脚本属性，保留有效发布路由。需要状态反馈时另建可读映射或配置 RPC。 |
| RPC | 请求、响应使用本次 RequestId，超时单位毫秒。发送成功、回执成功与现场动作结果分别核对。 |
写入前启用变量的 RPC 写许可，并确认其读写权限允许写入。先在独立订阅端看到确切 Topic 和正文，再核对接收设备反馈；仅看到发布成功不能完成控制验收。
设备调试
进入“开发配置 → 采集配置”，选择当前设备后点击“更多功能”并打开“调试”。
协议调试 · MqttClient
| 功能 | 作用 |
|---|---|
| 发布消息 | 填写 Topic、Payload、QoS 和 Retain，使用当前 MQTT 连接发布测试消息。 |
| 订阅管理 | 查看当前订阅，新增测试订阅或取消订阅。 |
| 刷新订阅 | 重新读取插件当前实际订阅列表，用于核对变量 Topic 是否生效。 |
调试要点
先用精确 Topic 订阅测试消息，再核对 JSONPath、条件脚本和变量更新时间；通配 Topic 会把匹配消息更新到同一变量。
验证重点
- 确认设备在线，并在“订阅管理”中看到变量配置使用的精确 Topic。
- 从测试发布端向该 Topic 发送一条已知 JSON，例如
{"data":{"temperature":31}}。 - 使用地址
SubscribeTopic=vendor/device;Path=$.data.temperature;的测试变量应更新为31，采集时间同步变化且无解析错误。 - 再测试一个不存在的首选 JSONPath 和有效备用 JSONPath，确认
||按从左到右选择第一个存在字段。 - 发布和 RPC 写入只使用测试 Topic；不要向生产控制 Topic 发送试验消息。
区分连接在线与数据新鲜度
- 使用精确 Topic 和一个简单路径，例如
SubscribeTopic=telemetry/line1;Path=$.data.value;，从独立发布端发送不同的新值，核对变量当前值和采集时间。 - 把“检查清除时间”设为业务允许的缺样秒数，例如
5。保持 Broker 连接，只停止这个主题的新消息，观察变量质量转为离线；正常检查约每200毫秒进行一次，允许调度误差。 - 再发一条新消息，确认变量重新在线。MQTT 保活维护会话，不能代替遥测的新鲜度判断。
- 有条件脚本时，先发返回
false的载荷，确认值和采集时间都未被替换；再发允许的载荷，确认路径取值与更新。拒绝不是写入0。
RPC 验收要使用本次请求的 RequestId。错误 ID、超时后的迟到回复或旧的保留回执不能完成新的请求；同时核对响应主题、成功字段、写入业务结果和真实源端反馈。
排障差异
- 设备无法连接：检查连接类型、Broker 地址和端口、客户端 ID、账号密码、MQTT 版本及 TLS 证书配置。
- 已连接但订阅列表没有变量 Topic：核对变量地址的
SubscribeTopic、QoS 和设备是否已重新加载配置。 - 收到消息但变量不更新：检查 JSONPath、Payload 是否为有效 JSON、条件脚本返回值和变量数据类型。
- 通配 Topic 的设备数据互相覆盖：改用精确 Topic，或在条件脚本中按
Topic过滤；客户端无法取得发布者 ClientId。 - RPC 超时：确认请求和响应 Topic 的
{RequestId}独占最后一个层级，并检查对端是否按同一 RequestId 回复。 - 保存失败：按错误提示检查属性名称是否拼写正确或重复、参数类型、JSONPath、主题通配符、读写权限组合以及 RPC 超时范围。