Partager via

AMQP 1.0 dans Microsoft Azure Service Bus : opérations basées sur les requêtes-réponses

  • Article

Cet article définit la liste des opérations basées sur les requêtes-réponses de Microsoft Azure Service Bus. Ces informations sont basées sur la première ébauche d’AMQP Management Version 1.0.

Pour un guide détaillé sur le protocole AMQP 1.0 au niveau des câbles qui explique comment Service Bus implémente et s’appuie sur la spécification technique AMQP OASIS, consultez le Guide du protocole AMQP 1.0 dans Azure Service Bus et Event Hubs.

Concepts

ServiceBusReceivedMessage / ServiceBusMessage

Représente un message Service Bus mappé à un message AMQP. Le mappage est défini dans le guide du protocole AMQP de Service Bus.

Attacher à un nœud de gestion d’entité

Toutes les opérations décrites dans ce document suivent un modèle demande/réponse sont limitées à une entité et nécessitent l’attachement à un nœud de gestion d’entité.

Crée un lien vers le nœud de gestion pour envoyer des demandes.

requestLink = session.attach(
role: SENDER,
   	target: { address: "<entity address>/$management" },
   	source: { address: ""<my request link unique address>" }
)

Crée un lien pour la réception des réponses à partir du nœud de gestion.

responseLink = session.attach(
role: RECEIVER,
	source: { address: "<entity address>/$management" }
   	target: { address: "<my response link unique address>" }
)

Transférer un message de demande

Transfère un message de demande.
Un état de transaction peut être ajouté éventuellement pour les opérations prenant en charge les transactions.

requestLink.sendTransfer(
        Message(
                properties: {
                        message-id: <request id>,
                        reply-to: "<my response link unique address>"
                },
                application-properties: {
                        "operation" -> "<operation>",
                }
        ),
        [Optional] State = transactional-state: {
                txn-id: <txn-id>
        }
)

Recevoir un message de réponse

Reçoit le message de réponse à partir du lien de réponse.

responseMessage = responseLink.receiveTransfer()

La réponse présente le format suivant :

Message(
properties: {
		correlation-id: <request id>
	},
	application-properties: {
			"statusCode" -> <status code>,
			"statusDescription" -> <status description>,
           },
)

Adresse d’entité Service Bus

Les entités Service Bus doivent être traitées comme suit :

Type d'entité Adresse Exemple
queue <queue_name> “myQueue”

“site1/myQueue”
topic <topic_name> “myTopic”

“site2/page1/myQueue”
abonnement <topic_name>/Subscriptions/<subscription_name> “myTopic/Subscriptions/MySub”

Opérations de message

Verrouillage du renouvellement du message

Étend le verrou d’un message en fonction de la durée de verrouillage définie sur la file d’attente ou l’abonnement.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:renew-lock
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
lock-tokens tableau d’uuid Oui Jetons de verrouillage de message à renouveler.

Notes

Le jeton de verrou fait ici référence à la propriété delivery-tag sur le message AMQP reçu. Si vous avez reçu un message différé et souhaitez renouveler son verrou, utilisez la propriété lock-token sur le message à la place de delivery-tag.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec.
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
expirations tableau d’horodatage Oui La nouvelle expiration du jeton de verrouillage de message correspond désormais aux jetons de verrouillage des demandes.

Lire furtivement un message

Lit furtivement les messages sans les verrouiller.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:peek-message
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
from-sequence-number long Oui Numéro de séquence à partir duquel commencer la lecture furtive.
message-count int Oui Nombre maximal de messages à lire furtivement.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK : a plus de messages

204 : aucun contenu – plus de messages
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
Cloud vers appareil liste des mappages Oui Liste de messages dans laquelle chaque mappage représente un message.

Le mappage représentant un message doit contenir les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
message tableau d’octets Oui Message codé en filaire AMPQ 1.0.

Message de planification

Messages de planification. Cette opération prend en charge la transaction.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:schedule-message
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
Cloud vers appareil liste des mappages Oui Liste de messages dans laquelle chaque mappage représente un message.

Le mappage représentant un message doit contenir les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
message-id string Oui amqpMessage.Properties.MessageId comme chaîne
session-id string Non amqpMessage.Properties.GroupId as string
partition-key string Non amqpMessage.MessageAnnotations.”x-opt-partition-key"
via-partition-key string Non amqpMessage.MessageAnnotations."x-opt-via-partition-key"
message tableau d’octets Oui Message codé en filaire AMPQ 1.0.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec.
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
sequence-numbers tableau de type long Oui Numéro de séquence des messages planifiés. Le numéro de séquence est utilisé pour annuler.

Annuler le message planifié

Annule les messages planifiés.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:cancel-scheduled-message
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
sequence-numbers tableau de type long Oui Numéros de séquence des messages planifiés pour annuler.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec.
statusDescription string Non Description de l’état.

Opérations de session

Verrouillage de renouvellement de session

Étend le verrou d’un message en fonction de la durée de verrouillage définie sur la file d’attente ou l’abonnement.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:renew-session-lock
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
session-id string Oui ID de la session.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK : a plus de messages

204 : aucun contenu – plus de messages
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
expiration timestamp Oui Nouvelle expiration.

Message de session de lecture furtive

Lit furtivement les messages de session sans les verrouiller.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:peek-message
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
from-sequence-number long Oui Numéro de séquence à partir duquel commencer la lecture furtive.
message-count int Oui Nombre maximal de messages à lire furtivement.
session-id string Oui ID de la session.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK : a plus de messages

204 : aucun contenu – plus de messages
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
Cloud vers appareil liste des mappages Oui Liste de messages dans laquelle chaque mappage représente un message.

Le mappage représentant un message doit contenir les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
message tableau d’octets Oui Message codé en filaire AMPQ 1.0.

Définir l’état d’une session

Définit l’état d’une session.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:set-session-state
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
session-id string Oui ID de la session.
session-state tableau d’octets Oui Données binaires opaques.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
statusDescription string Non Description de l’état.

Obtenir l’état d’une session

Obtient l’état d’une session.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:get-session-state
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
session-id string Oui ID de la session.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
session-state tableau d’octets Oui Données binaires opaques.

Énumérer les sessions

Énumère les sessions sur une entité de messagerie.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:get-message-sessions
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
last-updated-time timestamp Oui Filtre permettant d’inclure uniquement les sessions mises à jour après une durée donnée.
skip int Oui Ignore un certain nombre de sessions.
top int Oui Nombre maximal de sessions.

Remarque

Lorsque vous définissez LastUpdatedTime sur DateTime.MaxValue (dans .NET), la méthode Énumération des sessions retourne toutes les sessions, qu’elles aient un état ou non. Il est possible que DateTime.MaxValue dans .NET n’existe pas dans d’autres langages de programmation. Dans de tels cas, utilisez un horodatage égal à 253402300800000 millisecondes à partir d’Epoch (1er janvier 1970, 00:00:00 GMT), qui équivaut à DateTime.MaxValue dans .NET.

Response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK : a plus de messages

204 : aucun contenu – plus de messages
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
skip int Oui Nombre de sessions ignorées si le code d’état est 200.
sessions-ids tableau de chaînes Oui Tableau d’ID de session si le code d’état est 200.

Opérations relatives aux règles

Ajout de règle

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:add-rule
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
rule-name string Oui Nom de règle, à l’exception des noms d’abonnement et de rubrique.
rule-description map Oui Description de la règle comme indiqué dans la section suivante.

Le mappage rule-description doit inclure les entrées suivantes, où sql-filter et correlation-filter s’excluent mutuellement :

Clé Type de valeur Obligatoire Contenu de la valeur
sql-filter map Oui sql-filter, comme indiqué dans la section suivante.
correlation-filter map Oui correlation-filter, comme indiqué dans la section suivante.
sql-rule-action map Oui sql-rule-action, comme indiqué dans la section suivante.

Le mappage sql-filter doit inclure les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
expression string Oui Expression de filtre Sql.

Le mappage correlation-filter doit inclure au moins l’une des entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
correlation-id string Non
message-id string Non
to string Non
reply-to string Non
label string Non
session-id string Non
reply-to-session-id string Non
content-type string Non
properties carte Non Maps vers Service Bus ServiceBusMessage.Properties

Le mappage sql-rule-action doit inclure les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
expression string Oui Expression d’action SQL.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
statusDescription string Non Description de l’état.

Supprimer la règle

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:remove-rule
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
rule-name string Oui Nom de règle, à l’exception des noms d’abonnement et de rubrique.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
statusDescription string Non Description de l’état.

Obtenir les règles

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:enumerate-rules
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
top int Oui Le nombre de règles à extraire dans la page.
skip int Oui Le nombre de règles à ignorer. Définit l’index de départ (+1) dans la liste des règles.

response

Le message de réponse inclut les propriétés suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
rules liste des mappages Oui Liste des règles. Chaque règle est représentée par un mappage.

Chaque entrée de mappage dans la liste comprend les propriétés suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
rule-description objet décrit Oui com.microsoft:rule-description avec le code AMQP décrit 0x0000013700000004

com.microsoft.rule-description est une liste décrite. Il possède les propriétés suivantes :

Index Type de valeur Obligatoire Contenu de la valeur
0 liste décrite Oui filter, comme spécifié dans le tableau suivant.
1 liste décrite Oui ruleAction, comme spécifié plus loin dans cette section.
2 string Oui nom de la règle.
3 timestamp Oui horodatage.

filter peut être d’un des types suivants :

Nom du descripteur Code du descripteur Valeur
com.microsoft:sql-filter:list 0x000001370000006 Filtre SQL
com.microsoft:correlation-filter:list 0x000001370000009 Filtre de corrélation
com.microsoft:true-filter:list 0x000001370000007 Filtre True représentant 1=1
com.microsoft:false-filter:list 0x000001370000008 Filtre False représentant 1=0

com.microsoft:sql-filter:list est une liste décrite comprenant :

Index Type de valeur Obligatoire Contenu de la valeur
0 string Oui Expression de filtre SQL
1 int Oui Toujours 20. Cet entier est le niveau de compatibilité du filtre SQL. Il indique la version de syntaxe du filtre SQL.

com.microsoft:correlation-filter:list est une liste décrite comprenant :

Index (s’il existe) Type de valeur Contenu de la valeur
0 string ID de corrélation :
1 string ID de message
2 string À
3 string Adresse de réponse
4 string Étiquette
5 string ID de la session
6 string ID de session de réponse
7 string Type de contenu
8 Mappage Mappage des propriétés définies de l’application

ruleAction peut être d’un des types suivants :

Nom du descripteur Code du descripteur Valeur
com.microsoft:empty-rule-action:list 0x0000013700000005 Action de règle vide - aucune action de règle présente
com.microsoft:sql-rule-action:list 0x0000013700000006 Actions de règle SQL

com.microsoft:sql-rule-action:list est une liste décrite qui a deux éléments.

Index Type de valeur Obligatoire Contenu de la valeur
0 string Oui Expression de l’action de règle SQL
1 int Oui Toujours 20. Cet entier est le niveau de compatibilité du filtre SQL. Il indique la version de syntaxe du filtre SQL.

Opérations relatives aux messages différés

Recevoir par numéro de séquence

Reçoit des messages différés par numéro de séquence.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:receive-by-sequence-number
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
sequence-numbers tableau de type long Oui Numéros de séquence.
receiver-settle-mode ubyte Oui Mode de réglage du récepteur tel que spécifié dans AMQP core v1.0.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
statusDescription string Non Description de l’état.

Le corps du message de réponse doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
Cloud vers appareil liste des mappages Oui Liste de messages dans laquelle chaque mappage représente un message.

Le mappage représentant un message doit contenir les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
lock-token uuid Oui Jeton de verrouillage si receiver-settle-mode est 1.
message tableau d’octets Oui Message codé en filaire AMPQ 1.0.

Mettre à jour le statut de disposition

Met à jour le statut de disposition des messages différés. Cette opération prend en charge les transactions.

Requête

Le message de requête doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
opération string Oui com.microsoft:update-disposition
com.microsoft:server-timeout uint Non Délai d’expiration du serveur de l’opération en millisecondes.

Le corps du message de requête doit contenir une section amqp-value comprenant un mappage avec les entrées suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
disposition-status string Oui Terminé

abandonné

interrompu
lock-tokens tableau d’uuid Oui Jetons de verrouillage de message pour mettre à jour le statut de disposition.
deadletter-reason string Non Il est défini si l’état de disposition est défini sur interrompu.
deadletter-description string Non Il est défini si l’état de disposition est défini sur interrompu.
properties-to-modify carte Non Liste des propriétés de message réparti Service Bus à modifier.

response

Le message de réponse doit inclure les propriétés d’application suivantes :

Clé Type de valeur Obligatoire Contenu de la valeur
statusCode int Oui Code de réponse HTTP [RFC2616]

200 : OK-réussite, sinon échec
statusDescription string Non Description de l’état.

Étapes suivantes

Pour en savoir plus sur AMQP et Service Bus, consultez les liens suivants :