Berichten ophalen

De Get Messages bewerking haalt een of meer berichten op van de voorkant van de wachtrij.

Aanvraag

De Get Messages aanvraag kan als volgt worden samengesteld. U wordt aangeraden HTTPS te gebruiken. Vervang myaccount door de naam van uw opslagaccount en vervang door myqueue de naam van uw wachtrij:

Methode	Aanvraag-URI	HTTP-versie
GET	https://myaccount.queue.core.windows.net/myqueue/messages	HTTP/1.1

Aanvraag voor geëmuleerde opslagservice

Wanneer u een aanvraag doet voor de geëmuleerde opslagservice, geeft u de hostnaam van de emulator en de Azure Queue Storage-poort op als 127.0.0.1:10001, gevolgd door de naam van het geëmuleerde opslagaccount:

Methode	Aanvraag-URI	HTTP-versie
GET	http://127.0.0.1:10001/devstoreaccount1/myqueue/messages	HTTP/1.1

Zie Use the Azurite emulator for local Azure Storage development (De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling) voor meer informatie.

URI-parameters

De volgende aanvullende parameters kunnen worden opgegeven voor de aanvraag-URI.

Parameter	Beschrijving
numofmessages	Optioneel. Een niet-nul gehele waarde die het aantal berichten aangeeft dat uit de wachtrij moet worden opgehaald, tot een maximum van 32. Als er minder berichten zichtbaar zijn, worden de zichtbare berichten geretourneerd. Standaard wordt met deze bewerking één bericht uit de wachtrij opgehaald.
visibilitytimeout	Optioneel. Hiermee geeft u de nieuwe time-outwaarde voor zichtbaarheid, in seconden, ten opzichte van de servertijd. De standaardwaarde is 30 seconden. Een opgegeven waarde moet groter zijn dan of gelijk aan 1 seconde en mag niet langer zijn dan 7 dagen of langer dan 2 uur in REST-protocolversies die ouder zijn dan 18-08-2011. De zichtbaarheidstime-out van een bericht kan worden ingesteld op een waarde die later is dan de verlooptijd.
timeout	Optioneel. De timeout parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Azure Queue Storage-bewerkingen voor meer informatie.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader	Beschrijving
Authorization	Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
Date of x-ms-date	Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
x-ms-version	Optioneel. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
x-ms-client-request-id	Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Queue Storage bewaken voor meer informatie.

Aanvraagbody

Geen.

Antwoord

Het antwoord bevat een HTTP-statuscode en een set antwoordheaders.

Statuscode

Een geslaagde bewerking retourneert statuscode 200 (OK).

Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord kan ook extra standaard-HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Antwoordheader	Beschrijving
x-ms-request-id	Identificeert op unieke wijze de aanvraag die is gedaan en kan worden gebruikt om problemen met de aanvraag op te lossen. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
x-ms-version	Geeft de Versie van Azure Queue Storage aan die is gebruikt om de aanvraag uit te voeren. Deze header wordt geretourneerd voor aanvragen die zijn gemaakt op basis van versie 2009-09-19 en hoger.
Date	Een UTC-datum/tijd-waarde die wordt gegenereerd door de service, die de tijd aangeeft waarop het antwoord is gestart.
x-ms-client-request-id	Kan worden gebruikt om problemen met aanvragen en bijbehorende antwoorden op te lossen. De waarde van deze header is gelijk aan de waarde van de x-ms-client-request-id header als deze aanwezig is in de aanvraag en de waarde niet meer dan 1024 zichtbare ASCII-tekens bevat. Als de x-ms-client-request-id header niet aanwezig is in de aanvraag, is deze niet aanwezig in het antwoord.

Hoofdtekst van de reactie

De antwoord-XML voor de Get Messages bewerking wordt geretourneerd in de volgende indeling.

Het MessageID element is een GUID-waarde die het bericht in de wachtrij identificeert. Deze waarde wordt door Azure Queue Storage aan het bericht toegewezen en is ondoorzichtig voor de client. U kunt de waarde samen met de waarde van het PopReceipt element gebruiken om een bericht uit de wachtrij te verwijderen nadat u het hebt opgehaald met behulp van de Get Messages bewerking. De waarde van PopReceipt is ook ondoorzichtig voor de client. Het enige doel is ervoor te zorgen dat een bericht kan worden verwijderd met de bewerking Bericht verwijderen .

De InsertionTimeelementen , ExpirationTimeen TimeNextVisible worden weergegeven als UTC-waarden en opgemaakt zoals beschreven in RFC 1123.

Het DequeueCount element heeft de waarde 1 wanneer het bericht voor het eerst uit de wachtrij wordt verwijderd. Deze waarde wordt verhoogd telkens wanneer het bericht vervolgens uit de wachtrij wordt verwijderd.

Notitie

Het DequeueCount element wordt alleen geretourneerd in de antwoordtekst als de wachtrij is gemaakt met behulp van Azure Queue Storage versie 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>  

Voorbeeldantwoord

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>  

Autorisatie

Deze bewerking kan worden uitgevoerd door de accounteigenaar en door iedereen met een shared access signature die gemachtigd is om deze bewerking uit te voeren.

Opmerkingen

De inhoud van het bericht wordt opgehaald in de indeling die is gebruikt voor de bewerking Bericht plaatsen .

Wanneer een bericht uit de wachtrij wordt opgehaald, bevat het antwoord het bericht en een pop-ontvangstbevestigingswaarde, die vereist is om het bericht te verwijderen. Het bericht wordt niet automatisch verwijderd uit de wachtrij, maar nadat het is opgehaald, is het niet zichtbaar voor andere clients voor het tijdsinterval dat is opgegeven door de visibilitytimeout parameter.

Als er meerdere berichten worden opgehaald, heeft elk bericht een bijbehorende pop-ontvangstbevestiging. Het maximum aantal berichten dat tegelijkertijd kan worden opgehaald, is 32.

De client die het bericht ophaalt, wordt verwacht dat het bericht wordt verwijderd nadat het is verwerkt en vóór de tijd die is opgegeven door het TimeNextVisible element van het antwoord, dat wordt berekend op basis van de waarde van de visibilitytimeout parameter. De waarde van visibilitytimeout wordt toegevoegd aan het tijdstip waarop het bericht wordt opgehaald om de waarde van TimeNextVisiblete bepalen.

Vanwege klokscheefheid kan een bericht dat met een bepaalde visibilitytimeout waarde wordt opgehaald, opnieuw worden weergegeven voordat de opgegeven time-out is verstreken. Houd er rekening mee dat een client kan afleiden dat een bericht al door een andere client uit de wachtrij is verwijderd op basis van de pop-ontvangstbevestiging, die uniek is voor elke dequeuing van een bericht. Als de pop-ontvangstbevestiging van een client niet meer werkt om een bericht te verwijderen of bij te werken en de client een 404-fout (Niet gevonden) ontvangt, is het bericht door een andere client uit de wachtrij verwijderd.

Wanneer een consument een bericht ophaalt via Get Messages, wordt dat bericht doorgaans gereserveerd voor verwijdering totdat het interval voor zichtbaarheidstime-out is verlopen. Maar dit gedrag is niet gegarandeerd. Nadat het interval voor zichtbaarheidstime-out is verlopen, wordt het bericht weer zichtbaar voor andere gebruikers. Als het bericht vervolgens niet wordt opgehaald en verwijderd door een andere consument, kan de oorspronkelijke consument het bericht verwijderen met behulp van de oorspronkelijke pop-ontvangstbevestiging.

Wanneer een bericht voor de eerste keer wordt opgehaald, DequeueCount wordt de eigenschap ingesteld op 1. Als deze niet wordt verwijderd en vervolgens opnieuw wordt opgehaald, wordt de DequeueCount eigenschap verhoogd. De client kan deze waarde gebruiken om te bepalen hoe vaak een bericht is opgehaald.

Als de parameter visibilitytimeout of numofmessages buiten het bereik valt, retourneert de service statuscode 400 (Ongeldige aanvraag), samen met aanvullende foutinformatie, zoals wordt weergegeven in het volgende voorbeeld.

  
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>  
  

Zie ook

Azure Queue Storage-foutcodes
Aanvragen voor Azure Storage autoriseren
Status en foutcodes