zplCloud Blog
Stampa etichette con Azure Service Bus: la coda come trigger
Due forme di payload, una coda: un record JSON che compila un design o ZPL grezzo in una busta. Con PeekLock nulla va perso e nulla viene stampato due volte.
La coda è già il trigger
Se i tuoi sistemi parlano già tramite Azure Service Bus, il lavoro di stampa è un messaggio come un altro. Una sottoscrizione Data Streaming di tipo Service Bus consuma una coda o una sottoscrizione di topic e stampa ogni messaggio - nessun job di polling, nessun middleware di stampa, nessun server di stampa Windows tra il bus e la stampante.
La parte interessante è che un messaggio può essere una di due cose, e zplCloud decide per messaggio:
- Un record JSON - le chiavi dell'oggetto riempiono i binding di un design di etichetta. Usalo quando il mittente conosce i dati, non il layout.
- Una busta ZPL - un oggetto JSON che trasporta ZPL finito. Usalo quando il mittente produce già ZPL e ha solo bisogno che arrivi su una stampante.
Entrambi passano dalla stessa sottoscrizione; non configuri una modalità.
Configurare la sottoscrizione
| Campo | Valore |
|---|---|
| Tipo | Service Bus |
| Config di connessione | la stringa di connessione del namespace |
| Topic | nome della coda, o topic/Subscriptions/nomeSottoscrizione |
| Design etichetta | il design usato per i record JSON |
| Stampante | la stampante di destinazione predefinita |
La stringa di connessione è memorizzata cifrata AES a riposo.
Coda o topic è deciso dal campo Topic, per convenzione: se il valore contiene /Subscriptions/, viene trattato come topic/Subscriptions/nomeSottoscrizione; altrimenti è un nome di coda. Puoi anche lasciarlo vuoto e mettere EntityPath=printer nella stringa di connessione.
Le sottoscrizioni non vengono create automaticamente. Crea la sottoscrizione del topic una volta nel portale, Service Bus Explorer o l'emulatore (topic.1/Subscriptions/subscription.1); zplCloud la consuma e basta.
A differenza dell'integrazione Kafka, Service Bus gira solo lato cloud - il consumatore vive nel backend e si connette in uscita. Non esiste una variante agente on-prem, perché un namespace Service Bus è raggiungibile da internet comunque.
Payload A - un record JSON per un design
{ "ean": "4006381333930", "qty": 2, "dest": "Ramp 4" }
Le chiavi corrispondono ai binding del design per nome. Le chiavi senza binding vengono ignorate; i binding senza chiave si renderizzano vuoti.
Se il corpo non è JSON per niente, tutto il testo viene legato come $message - sufficiente per un'etichetta a campo singolo.
Un errore di render nomina il campo che l'ha causato invece di darti un messaggio SDK:
ZPL-Renderfehler bei qty: Wert 'zwei' → ...
Di solito è un problema di tipo o lunghezza: un campo numerico alimentato con una parola, o un valore più lungo di quanto il campo possa contenere.
Payload B - ZPL grezzo in una busta
Quando il mittente ha già lo ZPL, avvolgilo:
{
"schemaVersion": 1,
"zpl": "^XA^FO50,50^A0N,40,40^FDFrom the bus^FS^XZ",
"printer": "*"
}
Le regole perché questo venga trattato come busta sono deliberatamente severe:
- il corpo deve essere un oggetto JSON,
- deve avere una proprietà
zplche sia una stringa non vuota, - e deve inoltre portare
printer(stringa) oschemaVersion(numero).
L'ultima condizione è quella importante. Un record di dati normale che per caso contiene un campo chiamato zpl non viene dirottato e inviato grezzo alla stampante - passa comunque dal percorso del design. Se vuoi il comportamento a busta, dillo esplicitamente con printer o schemaVersion.
In modalità busta il design non viene toccato affatto: lo ZPL va alla stampante byte per byte.
Scegliere la stampante per messaggio
Il printer della busta sostituisce la stampante della sottoscrizione per quel messaggio. Due sentinelle trasmettono:
"*"o"all"- ogni stampante del workspace, Weblink e stampanti agente remote incluse.
Ogni destinazione conta come una propria etichetta contro la tua quota, quindi una trasmissione a otto stampanti fa otto etichette. Questo è il modello giusto per un avviso di cambio turno; è un errore costoso per un'etichetta per ordine.
Semantica di consegna: PeekLock, e cosa succede quando una stampa fallisce
Qui è dove un'integrazione a coda è affidabile o no. Il ricevitore gira in modalità PeekLock con PrefetchCount = 0 - ricevere non è cancellare, e nessun messaggio viene bufferizzato nel processo, quindi fermare o riavviare la sottoscrizione non inghiotte né duplica mai un lotto.
| Risultato | Cosa succede al messaggio |
|---|---|
| Stampato | Complete - il messaggio lascia il bus |
| Stampa fallita, consegna < 3 | Abandon - riconsegnato, poi un backoff di 10 s prima della ricezione successiva |
| Stampa fallita, consegna ≥ 3 | Dead-letter con motivo Print-Fehler (MaxDeliveryCount erreicht) e l'errore come descrizione |
Due conseguenze che vale la pena dire chiaramente:
- Un errore di stampa non ferma il consumatore. A differenza del percorso Kafka, la sottoscrizione continua a girare e ritenta; solo il singolo messaggio scala alla coda dei messaggi non recapitabili.
- Il successo è "i byte hanno raggiunto il socket della stampante". Una Zebra non conferma mai un'etichetta ZPL, quindi aspettare una conferma significherebbe uno stallo di 20 secondi e una stampa duplicata.
Completeavviene una volta che l'invio è riuscito - la colonna di debug mostrasent (no response)proprio per questo caso.
Poiché i messaggi falliti vengono dead-letterati invece che ritentati per sempre, la DLQ diventa la tua coda di etichette che non sono uscite. Questa è una lista su cui puoi agire, che è tutto il punto.
Keepalive di inattività
Se non arriva nulla per 60 secondi, la sottoscrizione invia un comando di wake alla stampante di destinazione. Le stampanti Link-OS passano a uno stato di basso consumo, e senza questo il primo messaggio dopo un periodo di silenzio paga la latenza di attivazione. Il keepalive gira fire-and-forget così non può bloccare il loop di ricezione e causare un accumulo.
Cosa vedi mentre gira
Ogni sottoscrizione mantiene un ring buffer degli ultimi 50 messaggi con l'anteprima del valore, il risultato di stampa e una traccia end-to-end:
bus=12ms design=3ms zpl=18ms print=64ms total=85ms
bus è il tempo tra l'accodamento e la ricezione - questa è la latenza della coda, non la tua. La colonna di debug registra inoltre la stampante, il numero di byte dello ZPL, lo stato HTTP e la risposta grezza.
I messaggi che falliscono vengono anche scritti in un log errori persistente, ma solo alla loro prima consegna. Senza quella protezione, i retry di Service Bus archivierebbero lo stesso messaggio errato tre volte.
Quote
Ogni etichetta in streaming conta come un render contro il piano del proprietario della sottoscrizione. Due messaggi distinti appaiono quando finisci:
Render-Limit erreicht (…/… Labels diesen Monat, Tarif …)- il budget mensile di render,Streaming-Kontingent erreicht (…)- il tetto di streaming specificamente.
Starter include lo streaming per i test, con un tetto di 100 etichette in streaming al mese. Pro include 2 endpoint di streaming (Kafka o Service Bus); ogni endpoint aggiuntivo costa 10 € al mese. Vedi la pagina prezzi.
Quale payload dovresti inviare
| Record JSON | Busta ZPL | |
|---|---|---|
| Il mittente deve conoscere | i nomi dei campi | il layout completo |
| Cambi di layout | modifica il design, mittenti invariati | ogni mittente deve essere ridistribuito |
| Stampante per messaggio | stampante della sottoscrizione | printer, incl. trasmissione * |
| Font, codici a barre, RFID | gestiti dal design | responsabilità tua |
Invia record se puoi. Il design resta modificabile da chi possiede l'etichetta, e un cambio di layout non richiede un release nel sistema che pubblica i messaggi. Invia buste quando lo ZPL esce da un sistema che non controlli, o quando un messaggio deve raggiungere più stampanti contemporaneamente.