Získání zpráv

Článek
08/05/2023

Operace Get Messages načte jednu nebo více zpráv z přední části fronty.

Žádost

Požadavek Get Messages může být vytvořen následujícím způsobem. Doporučujeme používat protokol HTTPS. Nahraďte myaccount názvem vašeho účtu úložiště a nahraďte myqueue názvem vaší fronty:

Metoda	Identifikátor URI žádosti	Verze PROTOKOLU HTTP
`GET`	`https://myaccount.queue.core.windows.net/myqueue/messages`	HTTP/1.1

Žádost o službu emulovaného úložiště

Při vytváření požadavku na službu emulovaného úložiště zadejte název hostitele emulátoru a port Azure Queue Storage jako 127.0.0.1:10001a název emulovaného účtu úložiště:

Metoda	Identifikátor URI žádosti	Verze PROTOKOLU HTTP
`GET`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages`	HTTP/1.1

Další informace najdete v tématu Použití emulátoru Azurite pro vývoj v místním úložišti Azure Storage.

Parametry identifikátoru URI

V identifikátoru URI požadavku je možné zadat následující další parametry.

Parametr	Popis
`numofmessages`	Nepovinný parametr. Nenulová celočíselná hodnota, která určuje počet zpráv, které se mají načíst z fronty, maximálně 32. Pokud je viditelných méně zpráv, vrátí se viditelné zprávy. Ve výchozím nastavení se z fronty pomocí této operace načte jedna zpráva.
`visibilitytimeout`	Nepovinný parametr. Určuje novou hodnotu časového limitu viditelnosti v sekundách vzhledem k času serveru. Výchozí hodnota je 30 sekund. Zadaná hodnota musí být větší nebo rovna 1 sekundě a ve verzích protokolu REST starších než 18. 8. 2011 nesmí být delší než 7 dní nebo delší než 2 hodiny. Časový limit viditelnosti zprávy se dá nastavit na hodnotu pozdější, než je čas vypršení platnosti.
`timeout`	Nepovinný parametr. Parametr se `timeout` vyjadřuje v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace služby Azure Queue Storage.

Hlavičky požadavku

Následující tabulka popisuje požadované a volitelné hlavičky požadavků.

Hlavička požadavku	Popis
`Authorization`	Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
`Date` nebo `x-ms-date`	Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
`x-ms-version`	Nepovinný parametr. Určuje verzi operace, která se má pro tento požadavek použít. Další informace najdete v tématu Správa verzí pro služby Azure Storage.
`x-ms-client-request-id`	Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem počtu znaků 1 kibibajt (KiB), který je zaznamenán v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá. Další informace najdete v tématu Monitorování služby Azure Queue Storage.

Text požadavku

Žádné

Odpověď

Odpověď obsahuje stavový kód HTTP a sadu hlaviček odpovědi.

Stavový kód

Úspěšná operace vrátí stavový kód 200 (OK).

Další informace o stavových kódech najdete v tématu Kódy stavu a chyb.

Hlavičky odpovědi

Odpověď na tuto operaci obsahuje následující hlavičky. Odpověď může také obsahovat další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.

Hlavička odpovědi	Description
`x-ms-request-id`	Jednoznačně identifikuje požadavek, který byl proveden, a lze ho použít k řešení potíží s požadavkem. Další informace najdete v tématu Řešení potíží s operacemi rozhraní API.
`x-ms-version`	Označuje verzi Azure Queue Storage, která se použila ke spuštění požadavku. Tato hlavička se vrátí pro požadavky provedené proti verzi 2009-09-19 a novější.
`Date`	Hodnota data a času UTC vygenerovaná službou, která označuje čas, kdy byla odpověď inicializována.
`x-ms-client-request-id`	Dá se použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě `x-ms-client-request-id` hlavičky, pokud se nachází v požadavku, a hodnota obsahuje maximálně 1 024 viditelných znaků ASCII. Pokud se hlavička `x-ms-client-request-id` v požadavku nenachází, v odpovědi se nezobrazí.

Text odpovědi

Kód XML odpovědi na Get Messages operaci se vrátí v následujícím formátu.

Element MessageID je hodnota GUID, která identifikuje zprávu ve frontě. Tato hodnota je přiřazena ke zprávě službou Azure Queue Storage a je neprůskladná pro klienta. K odstranění zprávy z fronty pomocí operace můžete použít hodnotu společně s hodnotou PopReceipt elementu Get Messages . Hodnota je PopReceipt také neprůžná pro klienta. Jeho jediným účelem je zajistit, aby zpráva byla odstraněna pomocí operace Odstranit zprávu .

Elementy InsertionTime, ExpirationTimea TimeNextVisible jsou reprezentovány jako hodnoty UTC a formátovány podle popisu v DOKUMENTU RFC 1123.

Element DequeueCount má hodnotu 1 při prvním vyřazení zprávy z fronty. Tato hodnota se při každém následném vyřazení zprávy z fronty navýší.

Poznámka

Element DequeueCount se vrátí v textu odpovědi pouze v případě, že byla fronta vytvořena pomocí Azure Queue Storage verze 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>

Ukázková odpověď

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>

Autorizace

Tuto operaci může provést vlastník účtu a kdokoli se sdíleným přístupovým podpisem, který má oprávnění k provedení této operace.

Poznámky

Obsah zprávy se načte ve formátu, který byl použit pro operaci Put Message .

Když se zpráva načte z fronty, odpověď bude obsahovat zprávu a hodnotu pop receipt, která je nutná k odstranění zprávy. Zpráva se automaticky neodstraní z fronty, ale po načtení se nezobrazí ostatním klientům po dobu určenou parametrem visibilitytimeout .

Pokud se načte více zpráv, každá zpráva má přidružené potvrzení pop. Maximální počet zpráv, které lze načíst současně, je 32.

Od klienta, který zprávu načte, se očekává, že zprávu odstraní po jejím zpracování a před časem určeným prvkem TimeNextVisible odpovědi, který se vypočítá na základě hodnoty parametru visibilitytimeout . Hodnota visibilitytimeout se přičte k času, kdy se zpráva načte, aby se určila hodnota TimeNextVisible.

Kvůli nerovnoměrné distribuci času se může zpráva načtená s určitým visibilitytimeout časovým limitem znovu zobrazit před uplynutím zadaného časového limitu. Všimněte si, že klient může odvodit, že zpráva již byla vyřazena z fronty jiným klientem na základě potvrzení pop, což je jedinečné pro každé vyřazení zprávy z fronty. Pokud pop receipt klienta už nefunguje při odstranění nebo aktualizaci zprávy a klient obdrží chybu 404 (Nenalezené), zpráva byla vyřazena z fronty jiným klientem.

Obvykle, když příjemce načte zprávu přes Get Messages, je tato zpráva vyhrazena pro odstranění, dokud nevyprší interval viditelnosti . Toto chování ale není zaručené. Po vypršení intervalu visibilitytimeout se zpráva znovu zobrazí ostatním příjemcům. Pokud zprávu následně nenačte a neodstraní jiný příjemce, může původní příjemce zprávu odstranit pomocí původního pop potvrzení.

Při prvním načtení zprávy je její DequeueCount vlastnost nastavena na hodnotu 1. Pokud se neodstraní a následně se znovu načte, DequeueCount vlastnost se navýší. Klient může tuto hodnotu použít k určení, kolikrát byla zpráva načtena.

Pokud je parametr visibilitytimeout nebo numofmessages mimo rozsah, vrátí služba stavový kód 400 (Chybný požadavek) spolu s dalšími informacemi o chybě, jak je znázorněno v následujícím příkladu.

  
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>

Viz také

Kódy chyb služby Azure Queue Storage
Autorizace požadavků do Služby Azure Storage
Stavové kódy a kódy chyb