发布动态 MQTT 测试数据

Payload Template 可以持续生成符合业务结构的动态 MQTT 测试数据，而不必手动修改每一条消息。本文将带你创建一条每 5 秒执行的定时消息，插入实时传感器快照 Recipe，并通过 Trace 的 SEND 与 RECV 记录确认数据已经成功发送和接收。

暗色截图记录的是 1.0.1 教程流程；浅色截图使用当前 1.5.0 源码，包含行内 JSON 行号与显式快照控件。两种主题的操作流程相同；较早安装版本的编辑器可能不同。

从已连接的测试 Client 开始

打开连接，选择隔离测试 Broker。本文使用隔离的本地 Broker；截图中的配置为：

• Broker：Docs Template Demo
• Protocol：mqtt
• Host：127.0.0.1
• Port：浅色截图使用 18883（历史暗色截图使用 2883）
• Client 名称：template-publisher
• Client ID：mqttable-docs-template-publisher
• MQTT Version：5.0

Mqttable 只连接这个 listener，不会启动 Broker。如果还没有已连接 Client，先完成 MQTT 快速入门或 Broker 与连接参数，看到这个 Client 显示已连接后再回来。如果 Broker 报告 Client ID 已占用，应停止旧教程连接，或由你自行修改后缀；本页使用的 Client ID 不是 Mqttable 自动生成的。

123

本教程不要使用生产 listener、共享客户 Topic、真实设备标识或敏感 Payload。

订阅 Demo Topic

在 mqttable-docs-template-publisher 行选择添加订阅，填写：

• Topic：mqttable/docs/template-series
• QoS：1
• Retain 处理方式：RH 0
• 不接收本地消息：关闭
• 保留发布时的 Retain 标志：关闭
• Subscription Identifier：留空
• Alert Monitor：关闭

不接收本地消息必须保持关闭：这样当前 Client 才能接收自己发布的消息。开启它会移除本教程的第二层 Broker 投递证据。

123

选择确认。只有 Client 行出现 Subscription Pill 后才继续。

123

创建定时 Payload Template

填写定时消息

在同一 Client 行选择添加消息。在新建定时消息中填写：

• Topic：mqttable/docs/template-series
• 发送间隔：5 秒
• Payload Format：JSON

5 秒是当前表单默认值，便于观察，同时不会制造不必要的高频流量。第一次发布会在完整等待一个 Interval 后发生。

123

插入实时传感器快照

选择模板，打开配方，找到实时传感器快照。这份 Recipe 会插入一份完整 JSON，不必逐字段拼装测试 Payload。

123

检查一份渲染样本

插入后，左侧是兼容 Liquid 的模板原文。发送区、发送窗口和定时消息编辑器会自动使用变量渲染模板，不再显示模板处理选项。即使草稿之前保存为固定内容，只要在当前载荷或主题中输入 Liquid 模板，也会启用渲染。工作台返回的固定快照仍保持固定内容，直到你加入模板原文。打开工具或预览不会发送消息。

编辑器先渲染主题，再把得到的主题作为载荷中 {{ topic }} 的值。{{ client_id }} 使用当前选择的客户端，保存后的草稿仍保留表达式原文。Bench 定时消息中，在主题或 Text／JSON／Sparkplug 原文里加入 {index}、{clientid} 等受支持的单大括号占位符，也会让原先的固定草稿恢复动态发送。

右侧是使用当前 Client、Topic、已启用的 Broker Variable 与内置动态 Helper 生成的一份快照。静态 JSON 默认收起预览，模板输出默认展开。快照显示 Settings timezone 下的生成时间，可显式刷新；编辑模板原文时会复用快照中的 uuid、now_ms 等内置变量。显式刷新或目标上下文变化时才重新生成这些变量；单纯等待不会改变预览。

123

当前“实时传感器快照”Recipe 的 Source 是：

{
  "ts": {{ now_ms }},
  "device": "{{ "motor" | device_id }}",
  "bearing_temp": {{ "bearing" | temperature }},
  "rpm": {{ 1200 | rpm: 1800 }},
  "pressure": {{ "hydraulic" | pressure }},
  "current": {{ "motor" | current }},
  "voltage": {{ "three_phase" | voltage }},
  "power_kw": {{ "pump" | power }},
  "vibration_z": {{ "z" | vibration }},
  "quality_good": {{ 0.98 | quality_good }}
}

预览不能证明稍后发出的字节。显式刷新的快照与每个定时 Tick 都可能生成不同值，Trace 才是发布证据。完成本例时请保留编辑器中的 Liquid 原文，不要用渲染后的快照替换它。

创建每 5 秒执行的 Schedule

关闭模板助手，为 Source、Preview 与最终投递设置留出空间。保存前逐项确认：

• Client：mqttable-docs-template-publisher
• Topic：mqttable/docs/template-series
• Interval：5 秒
• Payload Format：JSON
• 载荷原文：保留 Liquid 表达式，让每次定时发送都重新渲染
• QoS：1
• 保留消息：关闭
• MQTT 5.0 属性：可选值保留默认

123

选择创建定时消息。新 Pill 只能证明配置已保存并同步，还不能证明消息已被 Broker 投递。

123

等待约 15 秒，收集至少三次 5 秒渲染；然后删除定时消息，把 Trace 证据固定下来再开始比较。完成 RECV 检查前保留 Subscription。

在 Trace 中验证结果

比较多条 SEND 消息

在 Topic Filter 中输入 mqttable/docs/template-series。在 Grid 中比较至少两条 Route 为 SEND 的 PUBLISH。

123

成功的 SEND 序列应同时满足：

• 至少三条 PUBLISH；
• Topic 精确等于 mqttable/docs/template-series；
• QoS 为 1，Retain 为否；
• 每份 Payload 都是有效 JSON；
• 外层字段名称保持稳定；
• ts、motor_… 设备后缀和多项读数发生变化。

用 RECV 确认投递

选择匹配的 Route 为 RECV 的 PUBLISH，打开详情。SEND 证明 Mqttable 调用了 Publish；RECV 证明 Broker 把消息投递给前面创建的 Subscription。

123

不能把 Preview、Scheduled Message Pill 或单独一条 SEND 当成完整结果。只有变化的 SEND 序列与匹配的 RECV 证据同时存在，才算成功。

区分动态值与固定值

只有其它 Recipe 的 JSON Contract 与 Consumer 匹配时才应切换。用数据插入一个字段，用转换修改已有值，用语法添加受支持的 Liquid Control Flow。已启用 Broker Variable 可以加入少量非敏感环境值；它们是 Template Context，不是 Credential Store。

清理并理解能力边界

只删除本教程创建的两个对象：

1. mqttable-docs-template-publisher 上 Topic 为 mqttable/docs/template-series、5 秒、QoS 1 的定时消息。
2. 同一 Client、同一 Topic、QoS 1 的 Subscription。

经过 15 秒证据窗口后，定时消息应已删除；如果仍然存在，现在将它删除。等待至少 6 秒——超过一个完整 Interval——确认过滤后的 Trace Count 不再增加，再删除 Subscription。不要为了清理本教程而在共享 Broker 上直接选择清空消息；这会删除其它 Trace 证据。

123

Payload Template 在 Local Runtime 中没有独立 Pro 门禁。Remote Runtime 执行这条工作流需要当前在线 Pro entitlement、已登录 Session，以及 connections:write 与 messages:publish 权限。

未知 Variable、未知 Filter、无效参数、渲染后 JSON 错误、Timeout 与 Renderer 资源限制都会 fail closed，不会发布部分结果。定时消息没有消息数或结束时间字段，而且已保存 Client 重连后会恢复 Schedule，因此离开测试边界前必须删除它。

Literal 消息与 MQTT 5 投递选项见验证 MQTT 消息投递与定时发布。更深入的报文检查见 Trace。需要受控 Client 数、Rate、Duration、Threshold 与报告时，使用 Bench。