Utilisation de STOMP pour la gestion des messages

Présentation

STOMP est un protocole de messagerie ouvert qui peut améliorer l'efficacité de la production et de l'utilisation des messages car l'authentification est effectuée une fois par connexion, plutôt qu'une fois par demande. Le service Queue prend en charge les spécifications STOMP 1.0, 1.1 et 1.2. Vous pouvez utiliser à la fois STOMP et REST pour publier des messages et en utiliser dans la même file d'attente.

Pour plus d'informations sur la prise en charge de STOMP par Queue, reportez-vous aux sections suivantes :

• Connexion et authentification
• ENVOYER
• S'ABONNER
• SE DÉSINSCRIRE
• ACCUSÉ DE RÉCEPTION/ABANDON
• MESSAGE
• REÇU
• DÉCONNEXION
• ERREUR

Connexion et authentification

Les clients peuvent utiliser la trame CONNECT ou STOMP pour se connecter au service Queue sur son adresse de messages sur le port 61613. Pour des instructions détaillées sur la recherche de l'adresse de messages d'une file d'attente, reportez-vous à Adresse de messages.

L'authentification avec le protocole STOMP utilise des jetons d'authentification. Les jetons d'authentification doivent être encodés en Base64. Vous pouvez générer des jetons sur la page de détails de l'utilisateur de la console. Pour plus d'informations, reportez-vous à Utilisation des jetons d'authentification.

SEND

Utilisez la trame SEND pour générer des messages. Vous pouvez inclure les en-têtes suivants dans la trame SEND :

• destination : (requis) OCID (identificateur Oracle Cloud) de la file d'attente vers laquelle publier les messages. Vous pouvez éventuellement inclure un ID de canal à publier sur le canal indiqué. Exemples :

  <queue_OCID>/<channel_ID>

• receipt : (facultatif) si la trame SEND contient un en-tête receipt, Queue envoie au client une trame RECEIPT en cas de publication effectuée ou une trame ERROR en cas d'erreur.
  Remarque
  
  Si l'en-tête receipt est manquant, le service de file d'attente n'envoie pas de trame RECEIPT mais peut toujours envoyer une trame ERROR en cas d'erreur.

L'en-tête transaction et les en-têtes personnalisés ne sont pas pris en charge. Queue envoie une trame ERROR et ferme la connexion si des en-têtes non pris en charge sont inclus.

SUBSCRIBE

Employez la trame SUBSCRIBE pour utiliser des messages. Le cadre SUBSCRIBE est égal à une demande GetMessages d'interrogation longue. Tous les messages reçus sur la destination abonnée sont transmis au client sous forme de trames MESSAGE de la file d'attente. Vous pouvez inclure les en-têtes suivants dans la trame SUBSCRIBE :

• destination : (requis) OCID (identificateur Oracle Cloud) de la file d'attente à partir de laquelle utiliser des messages. Vous pouvez éventuellement inclure un filtre de canal à utiliser à partir du ou des canaux indiqués. Exemples :

  <queue_OCID>/<channel_ID_filter>

  Remarque
  
  Pour plus d'informations sur le filtrage, reportez-vous à Sélection de message.
• id : (requis) identifie l'abonnement. Le même ID doit être transmis par le client dans une trame UNSUBSCRIBE pour arrêter l'utilisation des messages.
• ack : (requis) seule la valeur client-individual est prise en charge. Cela signifie qu'une trame ACK supprime uniquement le message identifié au sein d'elle-même et non tous les messages distribués auparavant.
• visibility : (facultatif) durée pendant laquelle les messages utilisés seront visibles uniquement pour le client faisant la demande. Si l'en-tête est omis, le service Queue utilise le délai d'expiration de visibilité par défaut de la file d'attente.

En cas d'erreur, le service Queue renvoie une trame ERROR et ferme la connexion.

UNSUBSCRIBE

Utilisez la trame UNSUBSCRIBE pour empêcher le client STOMP de recevoir des messages de la file d'attente. Incluez l'en-tête suivant dans le cadre :

• id : (requis) identifie l'abonnement à arrêter. Cet ID a été utilisé dans la trame SUBSCRIBE correspondante.

ACK/NACK

Utilisez la trame ACK pour supprimer un message après sa réception et son traitement. Une trame ACK supprime uniquement le message identifié par l'en-tête id.

Utilisez la trame NACK pour informer Queue que le message n'a pas été traité. L'utilisation de la trame NACK met à jour la visibilité du message afin qu'il soit immédiatement visible pour les autres destinataires.

Les deux trames acceptent l'en-tête suivant, en fonction de la version du protocole :

• id : (requis pour STOMP version 1.2) ID du message à supprimer ou à mettre à jour.
• message-id : (requis pour STOMP version 1.1 ou 1.0) ID du message à supprimer ou à mettre à jour.

MESSAGE

La trame MESSAGE transmet les messages des abonnements au client STOMP. Une trame MESSAGE contient les en-têtes suivants :

• message-id :
  • Pour STOMP version 1.2 : identificateur interne unique du message. Utilisé à des fins de débogage uniquement.
  • Pour STOMP version 1.1 et version 1.0 : réception de message à utiliser avec les trames ACK et NACK.
• subscription : ID utilisé dans la trame SUBSCRIBE.
• destination : OCID (identificateur Oracle Cloud) de la file d'attente contenant les messages et ID de canal facultatif à publier vers un canal spécifié. Exemples :

  <queue_OCID>/<channel_ID>

• ack : pour STOMP version 1.2 uniquement, réception du message.
• content-type : type de charge utile, dans ce cas, plain/text.
• content-length : longueur de la charge utile ou message.
• expire-after : délai d'expiration du message, en millisecondes depuis la période.
• visible-after : durée de visibilité du message, en millisecondes depuis la période.
• delivery-count : nombre de fois où ce message a été distribué.
• oci-message-id : ID de message interne.

Une trame MESSAGE contient la charge utile du message en tant que corps de la trame.

RECEIPT

Le service Queue envoie une trame RECEIPT au client STOMP une fois qu'il a traité une trame SEND qui demandait une réception. Une trame RECEIPT inclut un en-tête receipt-id avec une valeur correspondant à l'en-tête de réception de la trame SEND.

Une trame RECEIPT est un accusé de réception indiquant que la trame client correspondante a été traitée par le serveur. Comme STOMP est basé sur un flux, la réception est également un accusé de réception cumulatif indiquant que toutes les trames précédentes ont été reçues par le serveur. Toutefois, ces trames précédentes peuvent ne pas encore être entièrement traitées. Si le client se déconnecte, les trames précédemment reçues doivent continuer à être traitées par le serveur.

DISCONNECT

Utilisez la trame DISCONNECT pour procéder à la déconnexion ou fermer la connexion au service Queue. Tous les abonnements associés à la connexion sont arrêtés. Vous pouvez inclure l'en-tête suivant dans la trame :

• receipt : (facultatif) Queue envoie une trame RECEIPT au client STOMP une fois que toutes les trames précédentes avec un en-tête receipt ont été traitées. Utilisez l'en-tête receipt pour les déconnexions progressives.

ERROR

Queue peut envoyer des trames ERROR en cas de problème. Après l'envoi de la trame ERROR, Queue ferme la connexion. La trame ERROR peut contenir les en-têtes suivants :

• message : brève description de l'erreur. Le corps contient des informations plus détaillées.
• receipt-id : valeur de l'en-tête receipt, si la trame à l'origine de l'erreur incluait un en-tête receipt.
• content-type : type de charge utile, si le corps contient plus de détails sur le message d'erreur.
• content-length : longueur de la charge utile ou détails du message d'erreur.

Le corps de la trame ERROR contient des informations détaillées sur l'erreur.