Passer au contenu principal
Les accusés de vos messages peuvent vous attendre dans une file durable par login HTTP jusqu’à ce que vous les acquittiez. Vous lisez cette file sur gRPC de l’une de deux manières — un flux serveur (Subscribe) ou du polling (Pull) — et retirez chaque accusé avec Ack. Les deux lisent la même file. C’est l’alternative à un endpoint webhook : rien à exposer sur internet, rien contre quoi la passerelle doit réessayer, et des accusés conservés jusqu’à ce que vous les ayez.

​
Quels accusés arrivent dans le flux

Un accusé est mis en file pour votre login quand toutes ces conditions sont réunies :
  • le message a été envoyé par votre login HTTP — sur gRPC ou sur REST ;
  • il a demandé des accusés — dlr: true en gRPC, "dlr": "yes" en REST — et cet accusé est l’un de ceux qu’il a demandés (dlr_level : 1 progression, 2 l’issue, 3 les deux) ;
  • il ne porte aucun dlr_url.
Le webhook l’emporte. Un message envoyé avec un dlr_url voit ses accusés envoyés à cette URL et jamais au flux. Les messages envoyés en SMPP n’y apparaissent jamais — ils reçoivent leurs accusés sur le bind.
Les envois REST peuvent aussi utiliser le flux. Sur une plateforme où gRPC et le flux sont activés, REST accepte "dlr": "yes" sans dlr_url, et ces accusés arrivent ici. Là où gRPC est désactivé, cette requête REST est toujours refusée 400, parce que les accusés n’auraient nulle part où aller. Voir POST /secure/send.
Un message qui atteint l’échéance des accusés — 24 heures par défaut — sans issue reçoit un dernier accusé UNKNOWN dans le flux, comme le ferait un webhook.

​
Le message Receipt

Le corps JSON du webhook, un champ par clé, plus deux champs de livraison à la fin : Les champs optionnels sont absents, pas vides, quand il n’y a rien à dire. Tout ce que le guide des accusés de livraison dit de level, stat et err s’applique sans changement.

​
La livraison est au moins une fois

1

Un accusé ne quitte la file que lorsque vous l'acquittez avec Ack

Ou lorsque la rétention le supprime — voir Limites et rétention.
2

Un accusé livré vous est loué pour 120 secondes

S’il n’est pas acquitté d’ici là, il est livré à nouveau — au Subscribe ou au Pull de votre login qui demande ensuite — avec delivery_count augmenté de un.
3

Un flux qui se termine rend ses accusés immédiatement

Quand un flux Subscribe se termine — vous annulez, la connexion tombe, la passerelle redémarre — les accusés qu’il avait livrés et que vous n’aviez pas acquittés sont libérés immédiatement, pas après le bail.
Donc après une reconnexion, on vous renvoie tout ce que vous n’aviez pas acquitté. C’est le rejeu, et c’est ce qui rend le flux sûr à travers les redémarrages des deux côtés.
Rendez votre traitement idempotent, et acquittez après, jamais avant.
  • Indexez-le sur id plus level — un accusé de progression et une issue pour un même message sont deux accusés.
  • Traitez un delivery_count supérieur à 1 comme une répétition possible.
  • N’appelez Ack qu’après avoir stocké un accusé ou agi dessus. Acquitter d’abord puis planter le perd définitivement.

​
Ack

already_gone n’est pas une erreur. Un Ack répété après un timeout est sûr, et c’est exactement dans ce cas que vous en répéterez un. Plus de 1000 jetons dans un seul appel est un INVALID_ARGUMENT. Un jeton fonctionne sur n’importe quel nœud de passerelle et à travers les redémarrages, mais seulement pour le login auquel il a été livré. Groupez vos acquittements : un Ack de 500 jetons coûte bien moins que 500 Ack d’un jeton.

​
Pull, le polling

Renvoie jusqu’à max accusés (au plus 1000), les plus anciens d’abord.
  • S’il n’y en a aucun en attente et que wait_seconds est supérieur à 0, il attend jusqu’à cette durée — 20 secondes au plus — et revient dès qu’un accusé arrive. C’est un long poll, et c’est ainsi que vous évitez une boucle active.
  • Avec wait_seconds: 0, il revient immédiatement, éventuellement vide.
Une boucle typique :
Pull convient à un job batch, à un worker qui se réveille sur un minuteur, ou à un langage dont vous préférez ne pas dépendre du support du streaming.

​
Subscribe, le streaming

Diffuse votre file : ce qui attend déjà d’abord, puis les nouveaux accusés à mesure qu’ils arrivent. window borne le nombre d’accusés livrés mais non acquittés que le flux détient. À la limite de la fenêtre, le flux se met en pause jusqu’à ce que vous appeliez Ack — sur n’importe quel canal. Non défini, ou au-dessus du maximum de la passerelle (1000 par défaut), c’est le maximum qui est utilisé.
Un flux qui semble s’arrêter après exactement window accusés attend vos acquittements. Acquittez au fur et à mesure, ou par petits lots — pas à la fin.

​
Plusieurs lecteurs partagent la file

Plusieurs flux Subscribe — et Pull — d’un même login partagent la file : chaque accusé va à exactement l’un d’eux à la fois. Utilisez cela pour répartir le traitement des accusés sur plusieurs workers. Pour donner des flux séparés à des applications séparées, donnez-leur des logins HTTP séparés.

​
Ordre

Au mieux, par ordre d’arrivée. Il n’y a aucune garantie d’ordre entre nœuds de passerelle, et un accusé relivré arrive après des accusés plus récents. Une issue peut arriver avant un accusé de progression pour le même message. Ordonnez par level — 2 est final — et par done_date, jamais par ordre d’arrivée. Une fois que vous détenez un accusé level: 2 pour un message, ignorez tout level: 1 qui arrive après.

​
Limites et rétention

Votre fournisseur peut modifier chacune de ces valeurs.
Un login qui demande des accusés et ne lit jamais son flux le remplit. Il atteint le plafond, et à partir de là les nouveaux accusés ne sont pas mis en file — les anciens, non lus, sont conservés à la place. Si vous activez les accusés sans dlr_url, faites tourner quelque chose qui les lit. Si vous n’en voulez jamais, envoyez dlr: false.

​
Voir aussi

Exemples

Boucles Subscribe, Pull et Ack en Python, Java et Go.

Le webhook d'accusé de livraison

Les mêmes champs, POSTés vers votre URL.