zplCloud Blog
用 Azure Service Bus 打印标签：队列即触发器
两种 payload 形态，一个队列：填充设计的 JSON 记录，或信封中的原始 ZPL。借助 PeekLock，消息不会丢失，也不会重复打印。
队列已经是触发器
如果你的系统已经通过 Azure Service Bus 通信，打印作业就像任何消息一样。Data Streaming 类型的 Service Bus 订阅消费一个队列或 topic 订阅并打印每条消息——没有轮询作业、没有打印中间件、没有介于总线与打印机之间的 Windows 打印服务器。
有意思的是消息可以二选一，zplCloud 逐条决定：
- JSON 记录 - 对象键填充标签设计的 binding。发送方知道数据而非版式时用这个。
- ZPL 信封 - 携带成品 ZPL 的 JSON 对象。发送方已产出 ZPL、只等上机时用这个。
两者走同一订阅；你不需要配置模式。
设置订阅
| 字段 | 值 |
|---|---|
| 类型 | Service Bus |
| 连接配置 | namespace 连接字符串 |
| Topic | 队列名，或 topic/Subscriptions/subscriptionName |
| 标签设计 | 用于 JSON 记录的设计 |
| 打印机 | 默认目标打印机 |
连接字符串静态存储时以 AES 加密。
队列还是 topic 由 Topic 字段按约定决定：如果值含 /Subscriptions/，则按 topic/Subscriptions/subscriptionName 处理；否则是队列名。你也可以留空并把 EntityPath=printer 放进连接字符串。
订阅不会自动创建。在门户、Service Bus Explorer 或模拟器中创建一次 topic 订阅（topic.1/Subscriptions/subscription.1）；zplCloud 只消费它。
与 Kafka 集成不同，Service Bus 仅云端运行——消费者在 backend 中并出站连接。没有 on-prem agent 变体，因为 Service Bus namespace 反正可通过互联网访问。
Payload A - 供设计用的 JSON 记录
{ "ean": "4006381333930", "qty": 2, "dest": "Ramp 4" }
键按名称匹配设计的 binding。无 binding 的键被忽略；无键的 binding 渲染为空。
如果 body 完全不是 JSON，整段文本绑定为 $message——单字段标签足够。
渲染错误会指名肇事字段，而不是丢给你一条 SDK 消息：
ZPL-Renderfehler bei qty: Wert 'zwei' → ...
通常是类型或长度问题：数字字段喂了词，或值超出字段容量。
Payload B - 信封中的原始 ZPL
当发送方已有 ZPL，包一层：
{
"schemaVersion": 1,
"zpl": "^XA^FO50,50^A0N,40,40^FDFrom the bus^FS^XZ",
"printer": "*"
}
被当作信封的规则刻意严格：
- body 必须是 JSON 对象，
- 必须有一个非空字符串的
zpl属性， - 并且还必须带
printer（字符串）或schemaVersion（数字）。
最后一条是关键。恰好含名为 zpl 字段的普通数据记录不会被劫持并原样发到打印机——它仍走设计路径。想要信封行为，就用 printer 或 schemaVersion 明说。
信封模式下设计完全不被触及：ZPL 逐字节到打印机。
逐条消息选择打印机
信封的 printer 覆盖该消息的订阅打印机。两个哨兵广播：
"*"或"all"- workspace 中每台打印机，Weblink 和远程 agent 打印机都算。
每个目标都作为自己的标签计入配额，所以向八台打印机广播就是八张标签。这是换班通知的正确模型；对按订单标签则是昂贵错误。
交付语义：PeekLock 与打印失败时
队列集成可靠与否就看这里。接收器以 PeekLock 模式运行，PrefetchCount = 0——接收不是删除，进程内不缓冲任何消息，因此停止或重启订阅永远不会吞掉或重复一批。
| 结果 | 消息下场 |
|---|---|
| 已打印 | Complete - 消息离开总线 |
| 打印失败，投递 < 3 | Abandon - 重新投递，然后下一次接收前 10 s 退避 |
| 打印失败，投递 ≥ 3 | 死信，原因 Print-Fehler (MaxDeliveryCount erreicht)，错误为描述 |
两点值得直说：
- 打印失败不停消费者。 与 Kafka 路径不同，订阅继续运行并重试；只有单条消息升级到死信队列。
- 成功意味着"字节到达打印机 socket"。 Zebra 从不确认 ZPL 标签，等待确认意味着 20 秒停顿和重复打印。发送成功后即
Complete——调试列正是为此显示sent (no response)。
因为失败消息被死信而非无限重试，DLQ 成为你没打出来的标签队列。那是你可以行动的清单，这正是全部意义。
空闲保活
如果 60 秒内无消息到达，订阅向目标打印机发送唤醒命令。Link-OS 打印机进入低功耗状态，没有它，安静期后的第一条消息要付唤醒延迟。keepalive 以 fire-and-forget 运行，不会阻塞接收循环造成堆积。
运行中看到什么
每个订阅保留最近 50 条消息的环形缓冲，带值预览、打印结果和端到端追踪：
bus=12ms design=3ms zpl=18ms print=64ms total=85ms
bus 是入队与接收之间的时间——那是队列延迟，不是你的。调试列还记录打印机、ZPL 字节数、HTTP 状态和原始响应。
失败消息也会写入持久错误日志，但仅在其首次投递。没有这道闸，Service Bus 自己的重试会把同一坏消息归档三次。
配额
每张流式标签按订阅所有者套餐计作一次渲染。用完时出现两条不同消息：
Render-Limit erreicht (…/… Labels diesen Monat, Tarif …)- 月度渲染预算，Streaming-Kontingent erreicht (…)- 专门针对流式上限。
Starter 含流式用于测试，上限每月 100 张流式标签。Pro 含 2 个流式端点（Kafka 或 Service Bus）；每增一个端点每月 € 10。参见定价页面。
该发哪种 payload
| JSON 记录 | ZPL 信封 | |
|---|---|---|
| 发送方需要知道 | 字段名 | 完整标签版式 |
| 版式变化 | 改设计，发送方不变 | 每个发送方都要重新部署 |
| 按消息打印机 | 订阅打印机 | printer，含 * 广播 |
| 字体、条码、RFID | 由设计处理 | 你的责任 |
能发记录就发记录。设计仍由标签主人编辑，版式变更不需要在发布消息的系统里发版。当 ZPL 来自你无法控制的系统，或一条消息必须同时到达多台打印机时，发信封。