Hämta meddelanden

Artikel
06/27/2023

Åtgärden Get Messages hämtar ett eller flera meddelanden längst fram i kön.

Förfrågan

Begäran Get Messages kan konstrueras på följande sätt. Vi rekommenderar att du använder HTTPS. Ersätt myaccount med namnet på ditt lagringskonto och ersätt myqueue med namnet på kön:

Metod	URI för förfrågan	HTTP-version
`GET`	`https://myaccount.queue.core.windows.net/myqueue/messages`	HTTP/1.1

Emulerad lagringstjänstbegäran

När du gör en begäran mot den emulerade lagringstjänsten anger du emulatorns värdnamn och Azure Queue Storage-porten som 127.0.0.1:10001, följt av namnet på det emulerade lagringskontot:

Metod	URI för förfrågan	HTTP-version
`GET`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages`	HTTP/1.1

Mer information finns i Använda Azurite-emulatorn för lokal Azure Storage-utveckling.

URI-parametrar

Följande ytterligare parametrar kan anges i begärande-URI:n.

Parameter	Beskrivning
`numofmessages`	Valfritt. Ett heltalsvärde som inte är noll och som anger hur många meddelanden som ska hämtas från kön, upp till högst 32. Om färre meddelanden visas returneras de synliga meddelandena. Som standard hämtas ett enda meddelande från kön med den här åtgärden.
`visibilitytimeout`	Valfritt. Anger det nya tidsgränsvärdet för synlighet i sekunder i förhållande till servertiden. Standardvärdet är 30 sekunder. Ett angivet värde måste vara större än eller lika med 1 sekund och får inte vara större än 7 dagar eller större än 2 timmar i REST-protokollversioner som är tidigare än 2011-08-18. Tidsgränsen för synlighet för ett meddelande kan anges till ett värde senare än förfallotiden.
`timeout`	Valfritt. Parametern `timeout` uttrycks i sekunder. Mer information finns i Ange tidsgränser för Azure Queue Storage-åtgärder.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden.

Begärandehuvud	Beskrivning
`Authorization`	Krävs. Anger auktoriseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
`Date` eller `x-ms-date`	Krävs. Anger Coordinated Universal Time (UTC) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
`x-ms-version`	Valfritt. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
`x-ms-client-request-id`	Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggningen har konfigurerats. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Queue Storage.

Begärandetext

Inga.

Svarsåtgärder

Svaret innehåller en HTTP-statuskod och en uppsättning svarshuvuden.

Statuskod

En lyckad åtgärd returnerar statuskoden 200 (OK).

Mer information om statuskoder finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller följande rubriker. Svaret kan också innehålla ytterligare HTTP-standardhuvuden. Alla standardhuvuden överensstämmer med HTTP/1.1-protokollspecifikationen.

Svarsrubrik	Description
`x-ms-request-id`	Identifierar unikt den begäran som gjordes och kan användas för att felsöka begäran. Mer information finns i Felsöka API-åtgärder.
`x-ms-version`	Anger den Azure Queue Storage-version som användes för att köra begäran. Det här huvudet returneras för begäranden som görs mot version 2009-09-19 och senare.
`Date`	Ett UTC-datum/tid-värde som genereras av tjänsten, vilket anger den tid då svaret initierades.
`x-ms-client-request-id`	Kan användas för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet `x-ms-client-request-id` för huvudet om det finns i begäran och värdet inte innehåller fler än 1 024 synliga ASCII-tecken. `x-ms-client-request-id` Om rubriken inte finns i begäran visas den inte i svaret.

Själva svaret

Svars-XML för åtgärden Get Messages returneras i följande format.

Elementet MessageID är ett GUID-värde som identifierar meddelandet i kön. Det här värdet tilldelas till meddelandet av Azure Queue Storage och är ogenomskinlig för klienten. Du kan använda värdet tillsammans med värdet för elementet PopReceipt för att ta bort ett meddelande från kön när du har hämtat det med hjälp Get Messages av åtgärden. Värdet för PopReceipt är också ogenomskinlig för klienten. Dess enda syfte är att säkerställa att ett meddelande kan tas bort med åtgärden Ta bort meddelande .

Elementen InsertionTime, ExpirationTimeoch TimeNextVisible representeras som UTC-värden och formateras enligt beskrivningen i RFC 1123.

Elementet DequeueCount har värdet 1 första gången meddelandet tas bort. Det här värdet ökas varje gång meddelandet därefter dequeueras.

Anteckning

Elementet DequeueCount returneras endast i svarstexten om kön skapades med hjälp av Azure Queue Storage 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>

Exempelsvar

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>

Auktorisering

Den här åtgärden kan utföras av kontoägaren och av alla som har en signatur för delad åtkomst som har behörighet att utföra den här åtgärden.

Kommentarer

Meddelandeinnehållet hämtas i det format som användes för put message-åtgärden .

När ett meddelande hämtas från kön innehåller svaret meddelandet och ett popkvittovärde som krävs för att ta bort meddelandet. Meddelandet tas inte bort automatiskt från kön, men när det har hämtats visas det inte för andra klienter för det tidsintervall som anges av parametern visibilitytimeout .

Om flera meddelanden hämtas har varje meddelande ett associerat popkvitto. Det maximala antalet meddelanden som kan hämtas samtidigt är 32.

Klienten som hämtar meddelandet förväntas ta bort meddelandet när det har bearbetats och före den tid som anges av elementet TimeNextVisible i svaret, som beräknas baserat på parameterns visibilitytimeout värde. Värdet visibilitytimeout för läggs till den tid då meddelandet hämtas för att fastställa värdet TimeNextVisibleför .

På grund av klocksnedställning kan ett meddelande som hämtas med en viss visibilitytimeout visas igen innan den angivna tidsgränsen har förflutit. Observera att en klient kan dra slutsatsen att ett meddelande redan har dequeued av en annan klient baserat på popkvittot, vilket är unikt för varje dequeuing av ett meddelande. Om en klients pop-kvitto inte längre fungerar för att ta bort eller uppdatera ett meddelande och klienten får ett 404-fel (hittades inte) har meddelandet tagits bort av en annan klient.

När en konsument hämtar ett meddelande via Get Messagesär meddelandet vanligtvis reserverat för borttagning tills tidsgränsen för synlighet upphör att gälla. Men det här beteendet är inte garanterat. När intervallet för synlighetstimeout upphör att gälla blir meddelandet återigen synligt för andra konsumenter. Om meddelandet inte hämtas och tas bort av en annan konsument kan den ursprungliga konsumenten ta bort meddelandet med hjälp av det ursprungliga popkvittot.

När ett meddelande hämtas för första gången anges dess DequeueCount egenskap till 1. Om den inte tas bort och den sedan hämtas igen DequeueCount ökas egenskapen. Klienten kan använda det här värdet för att avgöra hur många gånger ett meddelande har hämtats.

Om parameternsibilitytimeout eller numofmessages ligger inom intervallet returnerar tjänsten statuskod 400 (felaktig begäran) tillsammans med ytterligare felinformation, som du ser i följande exempel.

  
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>

Se även

Felkoder för Azure Queue Storage
Auktorisera begäranden till Azure Storage
Status- och felkoder