zplCloud Blog
Stampa etichette con Kafka: lo stream come trigger
Una sottoscrizione = topic + design + stampante. La parte che vale la pena leggere è cosa fa il consumatore quando una stampa fallisce.
Lo stream esiste già
Il tuo ERP o MES pubblica già eventi di ordini, messaggi di picking e numeri di serie su Kafka. Di solito quello stream finisce su uno schermo e un umano preme stampa.
La scheda Data Streaming rende lo stream il trigger: iscriviti a un topic, e ogni messaggio viene renderizzato con un design di etichetta e inviato a una stampante. Niente middleware, niente job di polling, niente server di stampa.
Due deployment:
- Cloud - la piattaforma consuma il topic da sola (Confluent Cloud, MSK, qualsiasi broker raggiungibile via internet).
- On-prem - un broker nella tua rete, consumato dall'agente CLI zplCloud. Le credenziali del broker non lasciano mai la tua rete.
Cosa lega una sottoscrizione
Quattro cose: un topic, un design di etichetta, una stampante e - in modalità cloud - la configurazione di connessione del broker. Per ogni messaggio la piattaforma:
1. analizza il valore come JSON e usa le chiavi dell'oggetto come binding dei campi,
2. renderizza il design con lo stesso motore del designer,
3. invia lo ZPL risultante alla stampante (Weblink, o una stampante remota su un agente CLI via TCP 9100 / USB).
Se il valore non è JSON, tutto il testo viene legato a $message - sufficiente per un'etichetta a campo singolo.
Configurazione di connessione
La configurazione è una stringa chiave=valore;, memorizzata cifrata AES a riposo:
BootstrapServers=pkc-xxxxx.eu-central-1.aws.confluent.cloud:9092;
GroupId=zplCloudPrinter;
SecurityProtocol=SaslSsl;SaslMechanism=Plain;
SaslUsername=<api-key>;SaslPassword=<api-secret>
Default applicati quando non li imposti:
| Impostazione | Default | Perché conta |
|---|---|---|
AutoOffsetReset | Latest | una nuova sottoscrizione parte dalla testa - non stampa l'intero storico del topic al primo avvio |
EnableAutoCommit | false | gli offset vengono confermati dalla piattaforma, dopo una stampa riuscita - non da un timer |
AutoCommitIntervalMs | 0 | irrilevante mentre l'auto-commit è spento |
AutoOffsetReset=Earliest è l'opt-in deliberato per riprodurre un topic. Impostalo solo se lo vuoi davvero: su un topic con storico, il primo avvio stampa tutto.
SCRAM (SaslMechanism=ScramSha256 / ScramSha512) e una CA personalizzata (SslCaLocation=…) sono supportati. Le chiavi sconosciute vengono passate alla configurazione del consumatore così come sono.
Per un broker on-prem, registralo sull'agente invece:
zplcloud proxy --agent "Lager" \
--kafka LOKAL="BootstrapServers=10.0.0.10:9092;GroupId=zplCloudConsumer"
L'agente segnala Kafka brokers: LOKAL. Quando una sottoscrizione ne ha bisogno, la piattaforma chiede all'agente di eseguire il consumatore - il broker resta irraggiungibile da internet.
La semantica di consegna, precisamente
Questa è la parte in cui la maggior parte delle integrazioni di streaming diventa vaga, quindi eccola esattamente come implementata:
- Il consumatore fa polling con un timeout di 30 secondi.
- Su un messaggio: renderizza, stampa, poi
Commit(msg)solo se la stampa è riuscita. - Se la stampa fallisce, l'offset non viene confermato e il consumatore si ferma. La sottoscrizione passa a disconnessa e mostra
Print failed: <error>. Non salta il messaggio e non gira in un loop di retry. - Poiché il default è
AutoOffsetReset=Latest, riavviare dopo un errore non riconsegna automaticamente il messaggio fallito. Se vuoi che il messaggio fallito venga ritentato al riavvio, mettiAutoOffsetReset=Earliestnella config - allora l'offset non confermato viene ripreso.
Il ragionamento: un'etichetta che non è stata stampata è un fatto operativo che qualcuno deve vedere. Avanzare in silenzio perderebbe un'etichetta fisica; ritentare per sempre bloccherebbe la partizione. Fermarsi la rende visibile e lascia l'offset dov'è.
ConsumeException - broker irraggiungibile, auth rifiutata, topic sparito - viene trattata diversamente. Non è un errore di stampa, quindi il consumatore ritenta con un backoff esponenziale che parte da 5 s e ha un tetto di 60 s, e l'ultimo errore del broker viene mostrato sulla sottoscrizione.
Keepalive di inattività
Se nessun messaggio arriva per 60 secondi, la piattaforma invia un comando di wake alla stampante di destinazione. Le stampanti Link-OS passano a uno stato di basso consumo; senza il keepalive, il primo messaggio dopo un periodo di silenzio paga la latenza di wake-up prima di stampare. Il keepalive tocca la stampante, non il topic - nessun offset viene consumato o confermato.
Creare la sottoscrizione
| Campo | Valore |
|---|---|
| Nome | Production labels |
| Tipo | Cloud (Internet) o On-Prem (via zplCloudCli) |
| Config di connessione | solo cloud: BootstrapServers=…;… |
| Agente + broker | solo on-prem: scegli l'agente e il chip broker |
| Topic | production.orders |
| Design etichetta | il design i cui binding corrispondono alle chiavi del messaggio |
| Stampante | stampante Weblink o stampante remota su un agente CLI |
Premi Avvia. La sottoscrizione mostra allora lo stato in diretta - connessa, ora dell'ultimo messaggio, ultimo offset, conteggio messaggi - e un log con i valori recenti dei messaggi e il loro risultato di stampa.
Forma del messaggio
{ "ean": "40063813", "qty": 2, "dest": "Ramp 4" }
Le chiavi corrispondono ai binding per nome. Le chiavi che nessun binding usa vengono ignorate; i binding senza chiave corrispondente si renderizzano vuoti. Progetta l'etichetta contro un messaggio reale prima di andare in produzione - Dati di prova nel designer accetta JSON incollato.
Comportamento al riavvio
Le sottoscrizioni attive ripartono quando la piattaforma riparte, e quelle on-prem ripartono quando l'agente CLI si riconnette. Una finestra di manutenzione notturna o una connessione caduta non richiedono che qualcuno prema di nuovo Avvia - con l'eccezione sopra: una sottoscrizione fermata da un errore di stampa resta ferma finché non sistemi la stampante e la avvii.
Piani
Lo streaming dati è misurato. Starter lo include per i test, con un tetto di 100 etichette in streaming al mese. Pro include 2 endpoint di streaming (Kafka / Azure Service Bus); ogni endpoint aggiuntivo costa 10 € al mese. Vedi la pagina prezzi.