Üzenetek lekérése

Cikk
06/27/2023

A Get Messages művelet egy vagy több üzenetet kér le az üzenetsor elejéről.

Kérés

A Get Messages kérelem az alábbiak szerint hozható létre. Javasoljuk, hogy HTTPS-t használjon. Cserélje le a myaccount elemet a tárfiók nevére, és cserélje le myqueue a elemet az üzenetsor nevére:

Metódus	Kérés URI-ja	HTTP-verzió
`GET`	`https://myaccount.queue.core.windows.net/myqueue/messages`	HTTP/1.1

Emulált tárolási szolgáltatás kérése

Amikor kérést küld az emulált tárolási szolgáltatásra, adja meg az emulátor gazdanevét és az Azure Queue Storage-portot , 127.0.0.1:10001majd az emulált tárfiók nevét:

Metódus	Kérés URI-ja	HTTP-verzió
`GET`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages`	HTTP/1.1

További információ: Az Azurite emulátor használata helyi Azure Storage-fejlesztéshez.

URI-paraméterek

A kérelem URI-ján a következő további paraméterek adhatók meg.

Paraméter	Leírás
`numofmessages`	Választható. Nem nulla egész szám, amely az üzenetsorból lekérendő üzenetek számát adja meg, legfeljebb 32-ig. Ha kevesebb üzenet látható, a rendszer visszaadja a látható üzeneteket. A rendszer alapértelmezés szerint egyetlen üzenetet kér le az üzenetsorból ezzel a művelettel.
`visibilitytimeout`	Választható. Az új láthatóság időtúllépési értékét adja meg másodpercben a kiszolgálói időhöz viszonyítva. Az alapértelmezett érték 30 másodperc. Egy megadott értéknek 1 másodpercnél nagyobbnak vagy egyenlőnek kell lennie, és nem lehet 7 napnál hosszabb, illetve 2 óránál hosszabb a 2011-08-18-nál korábbi REST protokollverziók esetében. Az üzenetek láthatósági időtúllépése a lejárati időnél későbbi értékre állítható be.
`timeout`	Választható. A `timeout` paraméter másodpercben van kifejezve. További információ: Időtúllépések beállítása az Azure Queue Storage-műveletekhez.

Kérésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti.

Kérelem fejléce	Leírás
`Authorization`	Kötelező. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérelmek engedélyezése az Azure Storage-ba.
`Date` vagy `x-ms-date`	Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérelmek engedélyezése az Azure Storage-ba.
`x-ms-version`	Választható. A kérelemhez használandó művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`x-ms-client-request-id`	Választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kibibyte (KiB) karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel. További információ: Az Azure Queue Storage monitorozása.

A kérés törzse

Nincsenek.

Reagálás

A válasz egy HTTP-állapotkódot és válaszfejléceket tartalmaz.

Állapotkód

A sikeres művelet a 200 -os állapotkódot adja vissza (OK).

További információ az állapotkódokról: Állapot- és hibakódok.

Válaszfejlécek

A műveletre adott válasz a következő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmazhat. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának.

Válaszfejléc	Description
`x-ms-request-id`	Egyedileg azonosítja a kérést, amely a kérés hibaelhárításához használható. További információ: API-műveletek hibaelhárítása.
`x-ms-version`	A kérés végrehajtásához használt Azure Queue Storage-verziót jelzi. Ezt a fejlécet a rendszer a 2009-09-19-es és újabb verzióval kapcsolatos kérések esetén adja vissza.
`Date`	A szolgáltatás által létrehozott UTC dátum/idő érték, amely a válasz indításának időpontját jelzi.
`x-ms-client-request-id`	A kérések és a megfelelő válaszok hibaelhárítására használható. A fejléc értéke megegyezik a `x-ms-client-request-id` kérelemben szereplő fejléc értékével, és az érték legfeljebb 1024 látható ASCII-karaktert tartalmaz. Ha a `x-ms-client-request-id` fejléc nem szerepel a kérelemben, akkor az nem jelenik meg a válaszban.

Választörzs

A művelet válasz XML-jének Get Messages visszaadása a következő formátumban történik.

Az MessageID elem egy GUID-érték, amely azonosítja az üzenetet az üzenetsorban. Ezt az értéket az Azure Queue Storage rendeli hozzá az üzenethez, és átlátszatlan az ügyfél számára. Az érték és az PopReceipt elem értékének együttes használatával törölheti az üzenetet az üzenetsorból, miután a művelettel lekérte.Get Messages Az értéke PopReceipt az ügyfél számára is átlátszatlan. Az egyetlen célja annak biztosítása, hogy egy üzenet törölhető legyen az Üzenet törlése művelettel.

A InsertionTime, ExpirationTimeés TimeNextVisible elemek UTC-értékekként jelennek meg, és az RFC 1123-as verziójában leírtak szerint vannak formázva.

Az DequeueCount elem értéke 1 az üzenet első lekérdezésekor. Ez az érték minden alkalommal növekszik, amikor az üzenetet később lekérdezik.

Megjegyzés

Az DequeueCount elem csak akkor lesz visszaadva a választörzsben, ha az üzenetsor az Azure Queue Storage 2009-09-19-es verziójával lett létrehozva.

<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>

Mintaválasz

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>

Engedélyezés

Ezt a műveletet a fióktulajdonos és bárki végrehajthatja, aki rendelkezik a művelet végrehajtásához engedéllyel rendelkező közös hozzáférésű jogosultságkóddal.

Megjegyzések

Az üzenet tartalma az Üzenet elküldése művelethez használt formátumban lesz lekérve.

Amikor lekér egy üzenetet az üzenetsorból, a válasz tartalmazza az üzenetet és egy pop nyugtaértéket, amely az üzenet törléséhez szükséges. Az üzenet nem törlődik automatikusan az üzenetsorból, de a lekérése után nem lesz látható a többi ügyfél számára a visibilitytimeout paraméter által megadott időintervallumban.

Több üzenet lekérése esetén mindegyik üzenethez tartozik egy pop-nyugta. Az egyszerre lekérhető üzenetek maximális száma 32.

Az üzenetet lekérő ügyfélnek várhatóan törölnie kell az üzenetet a feldolgozás után és a válasz eleme által TimeNextVisible megadott idő előtt, amely a visibilitytimeout paraméter értéke alapján lesz kiszámítva. A értéke visibilitytimeout hozzá lesz adva ahhoz az időponthoz, amikor az üzenet lekérése TimeNextVisibletörténik a értékének meghatározásához.

Az óraeltérés miatt egy bizonyos visibilitytimeout üzenet újból megjelenik, mielőtt a megadott időtúllépés eltelik. Vegye figyelembe, hogy az ügyfél arra következtethet, hogy egy üzenetet egy másik ügyfél már lekért az előugró nyugta alapján, amely egyedi az üzenetek minden egyes lekérdezésekor. Ha egy ügyfél előugró nyugtája már nem működik az üzenetek törlésére vagy frissítésére, és az ügyfél 404-ás (Nem található) hibaüzenetet kap, az üzenetet egy másik ügyfél törölte.

Általában, ha egy fogyasztó egy üzenetet a használatával Get Messageskér le, az üzenet törlésre van fenntartva, amíg a láthatósági időkorlát lejár. Ez a viselkedés azonban nem garantált. A láthatósági időkorlát lejárta után az üzenet ismét láthatóvá válik a többi felhasználó számára. Ha az üzenetet később nem kéri le és törli egy másik fogyasztó, az eredeti fogyasztó az eredeti előugró nyugtával törölheti az üzenetet.

Amikor első alkalommal kér le egy üzenetet, a tulajdonsága DequeueCount 1-re van állítva. Ha a rendszer nem törli, és később ismét lekéri, a DequeueCount tulajdonság növekszik. Az ügyfél ezt az értéket használhatja annak meghatározására, hogy hányszor kérték le az üzeneteket.

Ha a visibilitytimeout vagy a numofmessages paraméter kívül esik a tartományon, a szolgáltatás a 400-as állapotkódot (Hibás kérelem) adja vissza, valamint további hibainformációkat, amint az az alábbi példában látható.

  
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>

Lásd még

Azure Queue Storage-hibakódok
Kérések engedélyezése az Azure Storage-ba
Állapot- és hibakódok