zplCloud Blog
Impresión de etiquetas con Azure Service Bus: la cola como disparador
Dos formas de payload, una cola: un registro JSON que rellena un diseño o ZPL bruto en un sobre. PeekLock, para que nada se pierda y nada se imprima dos veces.
La cola ya es el disparador
Si tus sistemas ya se comunican por Azure Service Bus, el trabajo de impresión es un mensaje como cualquier otro. Una suscripción Data Streaming de tipo Service Bus consume una cola o una suscripción de topic e imprime cada mensaje - sin trabajos de polling, sin middleware de impresión, sin servidor de impresión Windows entre el bus y la impresora.
Lo interesante es que un mensaje puede ser una de dos cosas, y zplCloud decide por mensaje:
- Un registro JSON - las claves del objeto rellenan los bindings de un diseño de etiqueta. Úsalo cuando el remitente conoce los datos, no el diseño.
- Un sobre ZPL - un objeto JSON que transporta ZPL terminado. Úsalo cuando el remitente ya produce ZPL y solo necesita que llegue a una impresora.
Ambos pasan por la misma suscripción; no configuras un modo.
Configurar la suscripción
| Campo | Valor |
|---|---|
| Tipo | Service Bus |
| Configuración de conexión | la cadena de conexión del namespace |
| Topic | nombre de la cola, o topic/Subscriptions/nombreSuscripción |
| Diseño de etiqueta | el diseño usado para los registros JSON |
| Impresora | la impresora de destino por defecto |
La cadena de conexión se almacena cifrada con AES en reposo.
Cola o topic se decide por el campo Topic, por convención: si el valor contiene /Subscriptions/, se trata como topic/Subscriptions/nombreSuscripción; en caso contrario es un nombre de cola. También puedes dejarlo vacío y poner EntityPath=printer en la cadena de conexión.
Las suscripciones no se crean automáticamente. Crea la suscripción del topic una vez en el portal, Service Bus Explorer o el emulador (topic.1/Subscriptions/subscription.1); zplCloud solo la consume.
A diferencia de la integración Kafka, Service Bus se ejecuta solo en cloud - el consumidor vive en el backend y se conecta hacia afuera. No hay variante on-prem de agente, porque un namespace de Service Bus es accesible desde internet de todos modos.
Payload A - un registro JSON para un diseño
{ "ean": "4006381333930", "qty": 2, "dest": "Ramp 4" }
Las claves se comparan con los bindings del diseño por nombre. Las claves sin binding se ignoran; los bindings sin clave se renderizan vacíos.
Si el cuerpo no es JSON en absoluto, todo el texto se vincula como $message - suficiente para una etiqueta de un solo campo.
Un error de renderizado nombra el campo que lo causó en lugar de darte un mensaje del SDK:
ZPL-Renderfehler bei qty: Wert 'zwei' → ...
Eso suele ser un problema de tipo o longitud: un campo numérico alimentado con una palabra, o un valor más largo de lo que el campo puede contener.
Payload B - ZPL bruto en un sobre
Cuando el remitente ya tiene ZPL, envuélvelo:
{
"schemaVersion": 1,
"zpl": "^XA^FO50,50^A0N,40,40^FDFrom the bus^FS^XZ",
"printer": "*"
}
Las reglas para que esto se trate como un sobre son deliberadamente estrictas:
- el cuerpo debe ser un objeto JSON,
- debe tener una propiedad
zplque sea una cadena no vacía, - y debe llevar además
printer(cadena) oschemaVersion(número).
La última condición es la importante. Un registro de datos normal que casualmente contiene un campo llamado zpl no se secuestra ni se envía a la impresora en bruto - sigue pasando por la ruta del diseño. Si quieres el comportamiento de sobre, dilo explícitamente con printer o schemaVersion.
En modo sobre, el diseño no se toca en absoluto: el ZPL va a la impresora byte a byte.
Elegir la impresora por mensaje
El printer del sobre anula la impresora de la suscripción para ese mensaje. Dos centinelas transmiten:
"*"o"all"- todas las impresoras del workspace, Weblink e impresoras de agente remoto por igual.
Cada destino cuenta como una etiqueta propia contra tu cuota, así que una transmisión a ocho impresoras son ocho etiquetas. Ese es el modelo correcto para un aviso de cambio de turno; es un error caro para una etiqueta por pedido.
Semántica de entrega: PeekLock, y qué pasa cuando falla una impresión
Aquí es donde una integración de cola es o no de fiar. El receptor se ejecuta en modo PeekLock con PrefetchCount = 0 - recibir no es borrar, y no se almacenan mensajes en el proceso, así que detener o reiniciar la suscripción nunca se traga ni duplica un lote.
| Resultado | Qué pasa con el mensaje |
|---|---|
| Impreso | Complete - el mensaje sale del bus |
| Impresión fallida, entrega < 3 | Abandon - se reentrega, luego un backoff de 10 s antes de la siguiente recepción |
| Impresión fallida, entrega ≥ 3 | Dead-letter con motivo Print-Fehler (MaxDeliveryCount erreicht) y el error como descripción |
Dos consecuencias que vale la pena decir claramente:
- Un fallo de impresión no detiene el consumidor. A diferencia de la ruta Kafka, la suscripción sigue ejecutándose y reintenta; solo el mensaje individual escala a la cola de mensajes fallidos.
- El éxito es "los bytes llegaron al socket de la impresora". Una Zebra nunca confirma una etiqueta ZPL, así que esperar una confirmación significaría un atasco de 20 segundos y una impresión duplicada.
Completeocurre una vez que el envío ha tenido éxito - la columna de depuración muestrasent (no response)precisamente para este caso.
Como los mensajes fallidos se dead-letteran en lugar de reintentarse eternamente, la DLQ se convierte en tu cola de etiquetas que no salieron. Esa es una lista sobre la que puedes actuar, que es todo el punto.
Mantenimiento en inactividad
Si no llega nada durante 60 segundos, la suscripción envía un comando de activación a la impresora de destino. Las impresoras Link-OS pasan a un estado de bajo consumo, y sin esto el primer mensaje tras un periodo de silencio paga la latencia de activación. El keepalive se ejecuta fire-and-forget para que no pueda bloquear el bucle de recepción y causar una acumulación.
Lo que ves mientras se ejecuta
Cada suscripción mantiene un ring buffer de los últimos 50 mensajes con la vista previa del valor, el resultado de impresión y un rastro de extremo a extremo:
bus=12ms design=3ms zpl=18ms print=64ms total=85ms
bus es el tiempo entre el encolado y la recepción - esa es la latencia de la cola, no la tuya. La columna de depuración además registra la impresora, el número de bytes del ZPL, el estado HTTP y la respuesta bruta.
Los mensajes que fallan también se escriben en un registro de errores persistente, pero solo en su primera entrega. Sin esa protección, los propios reintentos de Service Bus archivarían el mismo mensaje malo tres veces.
Cuotas
Cada etiqueta en streaming cuenta como un render contra el plan del propietario de la suscripción. Aparecen dos mensajes distintos cuando te quedas sin:
Render-Limit erreicht (…/… Labels diesen Monat, Tarif …)- el presupuesto mensual de renders,Streaming-Kontingent erreicht (…)- el tope de streaming específicamente.
Starter incluye streaming para pruebas, con un tope de 100 etiquetas en streaming al mes. Pro incluye 2 endpoints de streaming (Kafka o Service Bus); cada endpoint adicional cuesta 10 € al mes. Consulta la página de precios.
Qué payload deberías enviar
| Registro JSON | Sobre ZPL | |
|---|---|---|
| El remitente necesita saber | nombres de campo | el diseño completo de la etiqueta |
| Cambios de diseño | edita el diseño, los remitentes no cambian | cada remitente debe redesplegarse |
| Impresora por mensaje | impresora de la suscripción | printer, incl. difusión * |
| Fuentes, códigos de barras, RFID | los gestiona el diseño | tu responsabilidad |
Envía registros si puedes. El diseño sigue siendo editable por los dueños de la etiqueta, y un cambio de diseño no requiere un release en el sistema que publica los mensajes. Envía sobres cuando el ZPL sale de un sistema que no controlas, o cuando un mensaje debe llegar a varias impresoras a la vez.