本页目录
ZeroMQ 订阅采集
ZeroMQ 订阅接收、主题过滤和变量映射采集驱动
选择入口
进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“ZeroMQCollectClient”。
支持的通道和数据类型
| 通道类型 | 配置前检查 |
|---|---|
| 插件内置连接 | 连接参数在设备动态属性中配置，不使用公共 TCP、UDP 或串口通道参数。 |
可选数据类型： 支持全部变量数据类型，按 JSON 提取结果选择；读取完整对象或数组时选择“对象”。
插件参数
ZeroMQ 采集客户端通过 NetMQ Socket 直接连接或绑定，不使用普通 TCP、UDP 或串口通道字段。读写超时、失败重试和数据解析顺序等采集公共属性仍按采集配置配置。
连接配置
| 参数 | 说明 |
|---|---|
| 连接地址 | 默认 tcp://127.0.0.1:5555。填写与发送端配对的 Endpoint，不能使用 TGateway Web 地址。 |
| Socket类型 | 默认 Sub。根据发送端选择 Sub、Pull 或 Router，配对关系见下文。 |
| 绑定模式 | 默认关闭。本端关闭时 Connect，开启时 Bind；与对端角色配套。 |
“Socket类型”选项为：Sub（订阅发布端）、Pull（接收 Push 端）和 Router（与 Dealer 配对并按身份回复）。默认是 Sub。绑定模式=是 时本端 Bind，关闭时本端 Connect；同一 Endpoint 只能由一端 Bind。
消息配置
| 参数 | 说明 |
|---|---|
| 订阅主题前缀 | 默认空。Sub 初始化时使用的主题前缀；空值订阅全部主题。加载变量后以变量地址中的主题为准。 |
该前缀用于 Sub 模式建立连接时的初始订阅；保存变量后，以当前变量地址中的订阅主题替换实际订阅，删除全部变量后清空订阅。Pull 和 Router 不使用该字段。
容量限制
| 参数 | 说明 |
|---|---|
| 高水位标记 | 默认 1000。设置采集 Socket 接收缓冲的高水位，不能当作已保存的历史条数。 |
高水位限制 Socket 接收缓冲，不是持久化队列；达到高水位时可能阻塞或丢弃消息，具体取决于配对的 Socket 类型。不能用它代替历史存储或离线补传。
日志诊断
| 参数 | 说明 |
|---|---|
| 详细日志 | 默认关闭。设备日志级别允许 Trace 且本项开启时，接收日志包含 Topic 与 Payload；关闭时只记录 Topic，仍受日志级别过滤。 |
缓存与可靠性
| 参数 | 说明 |
|---|---|
| 检查清除时间 | 默认 60000，单位毫秒。只读变量超过该时间没有成功更新时标记为离线，不是重连或失败重试间隔。 |
其他主题的消息、字段缺失或条件脚本拒绝的消息不会刷新该变量的采集时间。源值发送周期应短于此超时，并留出网络和处理余量。
地址规则
变量使用只读权限。地址采用 属性名称=值 命名字段，与 MQTT 采集使用相同的 JSONPath 和条件参数规则。以 Topic device/data 为例，第二帧使用以下 JSON 正文：
{
"Temperature": 25.6,
"Humidity": 60.5,
"Status": "Running"
}| 地址字段 | 说明 |
|---|---|
| SubscribeTopic | 必填，按前缀匹配实际消息主题，区分大小写；device/ 可以接收 device/data。不使用 MQTT 的 +、# 通配规则。 |
| Path | 必填，支持根节点 $、点号属性、数组下标、通配符、过滤器和用 || 分隔的候选路径；读取第一个存在的结果。属性优先精确匹配，只有唯一候选时才忽略大小写。 |
| Condition | 可选，选择数据转换类型的条件脚本。脚本接收完整 JSON 正文，返回真才更新变量；返回假或执行异常均不更新。 |
| ConditionParameters | 可选，条件脚本的输入参数文本对象，例如 {"Minimum":"20"}。在地址编辑器中选择脚本后填写参数，各变量独立保存。 |
SubscribeTopic=device/data;Path=$.Temperature提取数值25.6。SubscribeTopic=device/data;Path=$.missing||$.Status提取"Running"。SubscribeTopic=device/data;Path=$.Status;Condition=温度筛选;ConditionParameters={"Minimum":"20"}适用于已创建并声明Minimum数值输入的条件脚本。- 数组可以按字段筛选，例如
Path=$.items[?(@.code == 'A')].value；Path=$读取整个负载。 - 条件脚本可声明
Topic或ZeroMqTopic字符串输入读取实际消息主题；显式填写的输入参数优先于自动主题值。 - 字段值中的分号、百分号及空白使用 URI 转义；地址编辑器会自动处理。字段名不区分大小写，重复或未知字段、无效路径和参数会被拒绝。
- 消息必须是两帧：第一帧 Topic，第二帧 UTF-8 JSON Payload。
Router还包含身份帧和空分隔帧，插件会自动发送空响应确认。
特殊方法
| 方法 | 用途 | 参数 |
|---|---|---|
| SendDebugMessage | 发送 ZeroMQ 调试消息 | topic=消息主题,payload=消息正文 |
设备调试
进入“开发配置 → 采集配置”，选择当前设备后打开工作区顶部的“协议调试”页签。
专用调试页
协议调试页提供 Topic、消息正文、发布按钮和结果区。连接与订阅诊断需结合设备配置、变量值和设备日志查看。
| 功能 | 作用 |
|---|---|
| Topic / 消息正文 | 填写调试发送的主题及正文；Topic 必填，正文最多 64 KiB（UTF-8 字节数）。 |
| 发布 | 使用当前运行实例的 Socket 提交发送，不会新建独立发布端或直接向变量注入数据。 |
| 调试结果 | 查看发送请求返回或错误；仍需在对端核对实际收到的消息。 |
调试要点
Sub、Pull 是接收类型，采集验证应由独立的 Publisher 或 Push 端发送。Router 使用配对的 Dealer，按本页帧格式发送。协议页的发布结果不能代替接收和变量映射验证。
验证重点
- 确认发布端与采集端的 Endpoint、Socket 类型和 Bind/Connect 角色匹配，同一地址只由一端 Bind。
- 为只读测试变量配置
SubscribeTopic=device/data;Path=$.Temperature。 - 由配对的发送端发送 Topic
device/data、Payload{"Temperature":25.6}两帧，确认变量更新为25.6，且采集时间推进。 - 再使用条件脚本变量发送一条不满足条件的消息，确认变量不会被错误更新。
- 正式接入后观察高水位标记和详细日志，确认接收端没有持续积压或丢弃消息。
排障差异
- 发布或接收失败：检查连接地址、Socket 类型、绑定模式和防火墙；确认只有一端 Bind。
- 设备在线但变量不更新：核对 Topic、订阅主题前缀、Payload 字段名和条件脚本。
- 字段值为空：检查 JSONPath、属性名称和 Payload 格式；字段缺失或忽略大小写匹配存在歧义时不更新变量。
- 条件变量不更新：检查条件脚本、参数类型和日志中的脚本异常；脚本执行失败不会放行消息。
- Connect 模式显示在线但对端无数据：此状态只表示 Socket 初始化完成，不证明对端可达，需同时核对两端消息日志。
- 消息延迟或丢失：检查发送速度、接收处理速度和高水位标记，必要时降低测试频率。
- 调试发送未到达对端：确认当前 Socket 支持相应发送模式，并查看对端日志。
Sub/Pull的接收验证应从其配对发送端发起。