Obtenir les messages

  • Article

L'opération Get Messages récupère un ou plusieurs messages du début de la file d'attente.

Requête

La demande Get Messages peut être construite comme indiqué ci-dessous. Nous vous recommandons d’utiliser HTTPS. Remplacez myaccount par le nom de votre compte de stockage et remplacez par myqueue le nom de votre file d’attente :

Méthode URI de demande Version HTTP
GET https://myaccount.queue.core.windows.net/myqueue/messages HTTP/1.1

Demande de service de stockage émulée

Lorsque vous effectuez une demande auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et le port de stockage File d’attente Azure en tant que 127.0.0.1:10001, suivis du nom du compte de stockage émulé :

Méthode URI de demande Version HTTP
GET http://127.0.0.1:10001/devstoreaccount1/myqueue/messages HTTP/1.1

Pour plus d’informations, consultez Utiliser l’émulateur Azurite à des fins de développement local pour Stockage Azure.

Paramètres URI

Les paramètres supplémentaires suivants peuvent être spécifiés dans l'URI de la demande.

Paramètre Description
numofmessages facultatif. Une valeur entière différente de zéro qui spécifie le nombre de messages à récupérer de la file d'attente, avec un maximum de 32. Si moins de messages sont visibles, les messages visibles sont retournés. Par défaut, cette opération ne récupère qu'un seul message de la file d'attente.
visibilitytimeout Optionnel. Spécifie la nouvelle valeur de délai d’attente de visibilité, en secondes, par rapport à l’heure du serveur. La valeur par défaut est de 30 secondes.

Une valeur spécifiée doit être supérieure ou égale à 1 seconde et ne peut pas être supérieure à 7 jours ou supérieure à 2 heures sur les versions du protocole REST antérieures à 2011-08-18. Le délai de visibilité d’un message peut être défini sur une valeur postérieure à l’heure d’expiration.
timeout Optionnel. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Définir des délais d’attente pour les opérations de stockage file d’attente Azure.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires ou facultatifs.

En-tête de requête Description
Authorization Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
Date ou x-ms-date Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
x-ms-version Optionnel. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
x-ms-client-request-id Optionnel. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (Kio) enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes que le serveur reçoit. Pour plus d’informations, consultez Surveiller le stockage File d’attente Azure.

Corps de la demande

Aucun.

response

La réponse inclut un code d'état HTTP et un ensemble d'en-têtes de réponse.

Code d’état

Une opération réussie envoie le code d'état 200 (OK).

Pour plus d’informations sur les codes status, consultez Codes d’état et d’erreur.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse peut aussi inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

En-tête de réponse Description
x-ms-request-id Identifie de manière unique la demande qui a été effectuée et peut être utilisée pour résoudre la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API.
x-ms-version Indique la version de Stockage File d’attente Azure qui a été utilisée pour exécuter la demande. Cet en-tête est retourné pour les demandes effectuées sur la version 2009-09-19 et ultérieure.
Date Valeur de date/heure UTC générée par le service, qui indique l’heure à laquelle la réponse a été lancée.
x-ms-client-request-id Peut être utilisé pour résoudre les problèmes liés aux demandes et aux réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête x-ms-client-request-id s’il est présent dans la requête et que la valeur ne contient pas plus de 1 024 caractères ASCII visibles. Si l’en-tête x-ms-client-request-id n’est pas présent dans la demande, il ne sera pas présent dans la réponse.

Response body

La réponse XML pour l'opération Get Messages est renvoyée au format suivant.

L'élément MessageID est une valeur GUID qui identifie le message dans la file d'attente. Cette valeur est affectée au message par stockage file d’attente Azure et est opaque pour le client. Vous pouvez utiliser la valeur avec la valeur de l’élément PopReceipt pour supprimer un message de la file d’attente après l’avoir récupéré à l’aide de l’opération Get Messages . La valeur de PopReceipt est également opaque pour le client. Son seul objectif est de s’assurer qu’un message peut être supprimé avec l’opération Supprimer le message .

Les éléments InsertionTime, ExpirationTime et TimeNextVisible sont représentés en valeurs UTC et mis en forme selon la RFC 1123.

L'élément DequeueCount a une valeur de 1 la première fois que le message est dépilé. Cette valeur est incrémentée chaque fois que le message est dépilé.

Notes

L’élément DequeueCount est retourné dans le corps de la réponse uniquement si la file d’attente a été créée à l’aide du stockage File d’attente Azure version 2009-09-19.

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <PopReceipt>opaque-string-receipt-data</PopReceipt>  
      <TimeNextVisible>time-next-visible</TimeNextVisible>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>

Exemple de réponse

Response Status:  
HTTP/1.1 200 OK  
Response Headers:  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Fri, 16 Sep 2011 21:04:30 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
  
Response Body:  
<?xml version="1.0" encoding="utf-8"?>  
<QueueMessagesList>  
  <QueueMessage>  
    <MessageId>5974b586-0df3-4e2d-ad0c-18e3892bfca2</MessageId>  
    <InsertionTime>Fri, 09 Oct 2009 21:04:30 GMT</InsertionTime>  
    <ExpirationTime>Fri, 16 Oct 2009 21:04:30 GMT</ExpirationTime>  
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>  
    <TimeNextVisible>Fri, 09 Oct 2009 23:29:20 GMT</TimeNextVisible>  
    <DequeueCount>1</DequeueCount>  
    <MessageText>PHRlc3Q+dGhpcyBpcyBhIHRlc3QgbWVzc2FnZTwvdGVzdD4=</MessageText>  
  </QueueMessage>  
</QueueMessagesList>

Autorisation

Cette opération peut être exécutée par le propriétaire du compte et par toute personne qui dispose d'une signature d'accès partagé qui a l'autorisation d'exécuter cette opération.

Notes

Le contenu du message est récupéré dans le format utilisé pour l’opération Put Message .

Lorsqu'un message est récupéré à partir de la file d'attente, la réponse inclut le message et une valeur d'accusé pop, nécessaire à la suppression du message. Le message n’est pas automatiquement supprimé de la file d’attente, mais une fois récupéré, il n’est pas visible pour les autres clients pendant l’intervalle de temps spécifié par le visibilitytimeout paramètre .

Si plusieurs messages sont récupérés, chaque message a un accusé réception pop associé. Le nombre maximal de messages pouvant être récupérés en même temps est de 32.

Le client qui récupère le message est censé supprimer le message après son traitement et avant l’heure spécifiée par l’élément TimeNextVisible de la réponse, qui est calculée en fonction de la visibilitytimeout valeur du paramètre . La valeur de visibilitytimeout est ajoutée au moment où le message est récupéré pour déterminer la valeur de TimeNextVisible.

En raison de l’asymétrie de l’horloge, un message récupéré avec un certain visibilitytimeout peut réapparaître avant l’expiration du délai d’attente spécifié. Notez qu’un client peut déduire qu’un message a déjà été supprimé de la file d’attente par un autre client en fonction du reçu contextuel, qui est unique pour chaque retrait d’une file d’attente d’un message. Si le reçu contextuel d’un client ne fonctionne plus pour supprimer ou mettre à jour un message, et que le client reçoit une erreur 404 (introuvable), le message a été supprimé de la file d’attente par un autre client.

En règle générale, lorsqu’un consommateur récupère un message via Get Messages, ce message est réservé à la suppression jusqu’à l’expiration de l’intervalle de temps de visibilité . Mais ce comportement n’est pas garanti. Une fois l'intervalle visibilitytimeout expiré, le message est de nouveau visible par d'autres utilisateurs. Si le message n’est pas récupéré et supprimé par la suite par un autre consommateur, le consommateur d’origine peut supprimer le message à l’aide du reçu contextuel d’origine.

Quand un message est récupéré pour la première fois, sa propriété DequeueCount est définie à 1. Si elle n’est pas supprimée et qu’elle est récupérée par la suite, la DequeueCount propriété est incrémentée. Le client peut utiliser cette valeur pour déterminer combien de fois un message a été récupéré.

Si le paramètre visibilitytimeout ou numofmessages est hors limites, le service retourne status code 400 (Requête incorrecte), ainsi que des informations d’erreur supplémentaires, comme illustré dans l’exemple suivant.

  
HTTP/1.1 400 One of the query parameters specified in the request URI is outside the permissible range.  
Connection: Keep-Alive  
Content-Length: 455  
Via: 1.1 TK5-PRXY-22  
Date: Wed, 02 May 2012 19:37:23 GMT  
Content-Type: application/xml  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: 6a03526c-ca2c-4358-a63a-b5d096988533  
x-ms-version: 2011-08-18  
  
<?xml version="1.0" encoding="utf-8"?>  
   <Error>  
      <Code>OutOfRangeQueryParameterValue</Code>  
      <Message>One of the query parameters specified in the request URI is outside the permissible range.  
               RequestId:6a03526c-ca2c-4358-a63a-b5d096988533  
               Time:2012-05-02T19:37:24.2438463Z  
      </Message>  
     <QueryParameterName>numofmessages</QueryParameterName>  
     <QueryParameterValue>0</QueryParameterValue>  
     <MinimumAllowed>1</MinimumAllowed>  
     <MaximumAllowed>32</MaximumAllowed>  
   </Error>

Voir aussi

Codes d’erreur stockage file d’attente Azure
Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur