Impression d'étiquettes avec Azure Service Bus : la file comme déclencheur

La file est déjà le déclencheur

Si vos systèmes communiquent déjà via Azure Service Bus, le travail d'impression est un message comme un autre. Un abonnement Data Streaming de type Service Bus consomme une file ou un abonnement de topic et imprime chaque message - pas de travail de polling, pas de middleware d'impression, pas de serveur d'impression Windows entre le bus et l'imprimante.

L'intéressant, c'est qu'un message peut être l'une de deux choses, et zplCloud décide par message :

• Un enregistrement JSON - les clés de l'objet remplissent les bindings d'un design d'étiquette. Utilisez ceci quand l'expéditeur connaît les données, pas la mise en page.
• Une enveloppe ZPL - un objet JSON transportant du ZPL fini. Utilisez ceci quand l'expéditeur produit déjà du ZPL et a juste besoin qu'il arrive sur une imprimante.

Les deux passent par le même abonnement ; vous ne configurez pas de mode.

Configurer l'abonnement

Champ	Valeur
Type	Service Bus
Config de connexion	la chaîne de connexion du namespace
Topic	nom de la file, ou topic/Subscriptions/nomSouscription
Design d'étiquette	le design utilisé pour les enregistrements JSON
Imprimante	l'imprimante cible par défaut

La chaîne de connexion est stockée chiffrée AES au repos.

File ou topic est décidé par le champ Topic, par convention : si la valeur contient /Subscriptions/, elle est traitée comme topic/Subscriptions/nomSouscription ; sinon c'est un nom de file. Vous pouvez aussi le laisser vide et mettre EntityPath=printer dans la chaîne de connexion.

Les abonnements ne sont pas créés automatiquement. Créez l'abonnement de topic une fois dans le portail, Service Bus Explorer ou l'émulateur (topic.1/Subscriptions/subscription.1) ; zplCloud ne fait que le consommer.

Contrairement à l'intégration Kafka, Service Bus tourne côté cloud uniquement - le consommateur vit dans le backend et se connecte vers l'extérieur. Il n'y a pas de variante agent on-prem, car un namespace Service Bus est accessible depuis internet de toute façon.

Payload A - un enregistrement JSON pour un design

{ "ean": "4006381333930", "qty": 2, "dest": "Ramp 4" }

Les clés correspondent aux bindings du design par nom. Les clés sans binding sont ignorées ; les bindings sans clé se rendent vides.

Si le corps n'est pas du JSON du tout, tout le texte est lié comme $message - suffisant pour une étiquette à champ unique.

Une erreur de rendu nomme le champ qui l'a causée plutôt que de vous donner un message SDK :

ZPL-Renderfehler bei qty: Wert 'zwei' → ...

C'est généralement un problème de type ou de longueur : un champ numérique nourri avec un mot, ou une valeur plus longue que le champ ne peut contenir.

Payload B - ZPL brut dans une enveloppe

Quand l'expéditeur a déjà le ZPL, enveloppez-le :

{
  "schemaVersion": 1,
  "zpl": "^XA^FO50,50^A0N,40,40^FDFrom the bus^FS^XZ",
  "printer": "*"
}

Les règles pour que cela soit traité comme une enveloppe sont délibérément strictes :

• le corps doit être un objet JSON,
• il doit avoir une propriété zpl qui est une chaîne non vide,
• et il doit en plus porter printer (chaîne) ou schemaVersion (nombre).

La dernière condition est l'importante. Un enregistrement de données ordinaire qui contient par hasard un champ nommé zpl n'est pas détourné et envoyé brut à l'imprimante - il passe toujours par le chemin du design. Si vous voulez le comportement d'enveloppe, dites-le explicitement avec printer ou schemaVersion.

En mode enveloppe, le design n'est pas touché du tout : le ZPL va à l'imprimante octet pour octet.

Choisir l'imprimante par message

Le printer de l'enveloppe remplace l'imprimante de l'abonnement pour ce message. Deux sentinelles diffusent :

• "*" ou "all" - chaque imprimante de l'espace de travail, Weblink et imprimantes d'agent distant incluses.

Chaque cible compte comme une étiquette propre contre votre quota, donc une diffusion vers huit imprimantes fait huit étiquettes. C'est le bon modèle pour un avis de changement d'équipe ; c'est une erreur coûteuse pour une étiquette par commande.

Sémantique de livraison : PeekLock, et ce qui arrive quand une impression échoue

C'est là qu'une intégration de file est digne de confiance ou non. Le récepteur tourne en mode PeekLock avec PrefetchCount = 0 - recevoir n'est pas supprimer, et aucun message n'est mis en tampon dans le processus, donc arrêter ou redémarrer l'abonnement n'avale ni ne duplique jamais un lot.

Résultat	Ce qui arrive au message
Imprimé	Complete - le message quitte le bus
Impression échouée, livraison < 3	Abandon - redélivré, puis un backoff de 10 s avant la réception suivante
Impression échouée, livraison ≥ 3	Dead-letter avec motif Print-Fehler (MaxDeliveryCount erreicht) et l'erreur en description

Deux conséquences qui méritent d'être dites clairement :

• Un échec d'impression n'arrête pas le consommateur. Contrairement au chemin Kafka, l'abonnement continue de tourner et réessaie ; seul le message individuel escalade vers la file des lettres mortes.
• Le succès, c'est « les octets ont atteint le socket de l'imprimante ». Une Zebra n'accuse jamais réception d'une étiquette ZPL, donc attendre une confirmation signifierait un blocage de 20 secondes et une impression dupliquée. Complete se produit une fois l'envoi réussi - la colonne de débogage montre sent (no response) précisément pour ce cas.

Parce que les messages échoués sont dead-letterés plutôt que réessayés éternellement, la DLQ devient votre file des étiquettes qui ne sont pas sorties. C'est une liste sur laquelle vous pouvez agir, ce qui est tout l'intérêt.

Keepalive d'inactivité

Si rien n'arrive pendant 60 secondes, l'abonnement envoie une commande de réveil à l'imprimante cible. Les imprimantes Link-OS passent en état de faible consommation, et sans cela le premier message après une période calme paie la latence de réveil. Le keepalive tourne en fire-and-forget pour ne pas bloquer la boucle de réception et causer un empilement.

Ce que vous voyez pendant l'exécution

Chaque abonnement garde un tampon circulaire des 50 derniers messages avec l'aperçu de la valeur, le résultat d'impression et une trace de bout en bout :

bus=12ms design=3ms zpl=18ms print=64ms total=85ms

bus est le temps entre la mise en file et la réception - c'est la latence de la file, pas la vôtre. La colonne de débogage enregistre en plus l'imprimante, le nombre d'octets du ZPL, le statut HTTP et la réponse brute.

Les messages qui échouent sont aussi écrits dans un journal d'erreurs persistant, mais uniquement à leur première livraison. Sans cette garde, les propres relances de Service Bus classeraient trois fois le même mauvais message.

Quotas

Chaque étiquette en streaming compte comme un rendu contre le plan du propriétaire de l'abonnement. Deux messages distincts apparaissent quand vous êtes à court :

• Render-Limit erreicht (…/… Labels diesen Monat, Tarif …) - le budget mensuel de rendus,
• Streaming-Kontingent erreicht (…) - le plafond de streaming spécifiquement.

Starter inclut le streaming pour les tests, plafonné à 100 étiquettes en streaming par mois. Pro inclut 2 endpoints de streaming (Kafka ou Service Bus) ; chaque endpoint supplémentaire coûte 10 € par mois. Voir la page de prix.

Quel payload devriez-vous envoyer

	Enregistrement JSON	Enveloppe ZPL
L'expéditeur doit connaître	les noms de champs	la mise en page complète
Changements de mise en page	modifiez le design, expéditeurs inchangés	chaque expéditeur doit être redéployé
Imprimante par message	imprimante de l'abonnement	printer, incl. diffusion *
Polices, codes-barres, RFID	gérés par le design	votre responsabilité

Envoyez des enregistrements si vous pouvez. Le design reste modifiable par ceux qui possèdent l'étiquette, et un changement de mise en page ne nécessite pas de release dans le système qui publie les messages. Envoyez des enveloppes quand le ZPL sort d'un système que vous ne contrôlez pas, ou quand un message doit atteindre plusieurs imprimantes à la fois.

Liens

• Automatisation - API, webhooks, lots, streaming
• Intégrations - Kafka, Service Bus, bases de données
• Cloud Integration / Connections
• Tarifs