Nachrichten abrufen

  • Artikel

Der Get Messages-Vorgang ruft eine oder mehrere Nachrichten ausgehend vom Anfang der Warteschlange ab.

Anforderung

Die Get Messages-Anforderung kann wie folgt erstellt werden. Es wird empfohlen, HTTPS zu verwenden. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos und durch myqueue den Namen Ihrer Warteschlange:

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

Emulierte Speicherdienstanforderung

Wenn Sie eine Anforderung an den emulierten Speicherdienst stellen, geben Sie den Emulatorhostnamen und den Azure Queue Storage-Port als 127.0.0.1:10001an, gefolgt vom namen des emulierten Speicherkontos:

Methode Anforderungs-URI HTTP-Version
GET http://127.0.0.1:10001/devstoreaccount1/myqueue/messages HTTP/1.1

Weitere Informationen finden Sie unter Verwenden des Azurite-Emulators für lokale Azure Storage-Entwicklung.

URI-Parameter

Im Anforderungs-URI können die folgenden zusätzlichen Parameter angegeben werden.

Parameter BESCHREIBUNG
numofmessages Optional. Ein ganzzahliger Wert ungleich 0 (null), der die Anzahl der Nachrichten angibt, die aus der Warteschlange abgerufen werden sollen; der maximale Wert beträgt 32. Wenn weniger Nachrichten sichtbar sind, werden die sichtbaren Nachrichten zurückgegeben. Standardmäßig wird mit diesem Vorgang eine einzige Nachricht aus der Warteschlange abgerufen.
visibilitytimeout Optional. Gibt den neuen Timeoutwert für die Sichtbarkeit in Sekunden relativ zur Serverzeit an. Der Standardwert ist 30 Sekunden.

Ein angegebener Wert muss größer oder gleich 1 Sekunde sein und darf bei REST-Protokollversionen, die älter als 18.08.2011 sind, nicht größer als 7 Tage oder größer als 2 Stunden sein. Das Sichtbarkeitstimeout einer Nachricht kann auf einen Wert festgelegt werden, der später als die Ablaufzeit ist.
timeout Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Queue Storage-Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

Anforderungsheader BESCHREIBUNG
Authorization Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
Date oder x-ms-date Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
x-ms-version Optional. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen von Azure Queue Storage.

Anforderungstext

Keine.

Antwort

Die Antwort enthält den HTTP-Statuscode und einen Satz von Antwortheadern.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben.

Weitere Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann außerdem weitere HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader BESCHREIBUNG
x-ms-request-id Identifiziert eindeutig die Anforderung, die gestellt wurde, und kann zur Problembehandlung für die Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
x-ms-version Gibt die Azure Queue Storage-Version an, die zum Ausführen der Anforderung verwendet wurde. Dieser Header wird für Anforderungen zurückgegeben, die für Version 2009-09-19 und höher ausgeführt werden.
Date Ein UTC-Datums-/Uhrzeitwert, der vom Dienst generiert wird, der den Zeitpunkt angibt, zu dem die Antwort initiiert wurde.
x-ms-client-request-id Kann zur Problembehandlung von Anforderungen und entsprechenden Antworten verwendet werden. Der Wert dieses Headers ist gleich dem Wert des x-ms-client-request-id Headers, wenn er in der Anforderung vorhanden ist und der Wert nicht mehr als 1.024 sichtbare ASCII-Zeichen enthält. Wenn der x-ms-client-request-id Header in der Anforderung nicht vorhanden ist, ist er in der Antwort nicht vorhanden.

Antworttext

Das Antwort-XML für den Get Messages-Vorgang wird im folgenden Format zurückgegeben.

Das MessageID-Element ist ein GUID-Wert, der die Nachricht in der Warteschlange identifiziert. Dieser Wert wird der Nachricht von Azure Queue Storage zugewiesen und ist für den Client undurchsichtig. Sie können den Wert zusammen mit dem Wert des PopReceipt Elements verwenden, um eine Nachricht aus der Warteschlange zu löschen, nachdem Sie sie mithilfe des Get Messages Vorgangs abgerufen haben. Der Wert von PopReceipt ist auch für den Client undurchsichtig. Der einzige Zweck besteht darin, sicherzustellen, dass eine Nachricht mit dem Vorgang Nachricht löschen gelöscht werden kann.

Die Elemente InsertionTime, ExpirationTime und TimeNextVisible werden als UTC-Werte dargestellt und sind entsprechend der Beschreibung in RFC 1123 formatiert.

Das DequeueCount-Element weist den Wert 1 auf, wenn die Nachricht das erste Mal aus der Warteschlange entfernt wird. Dieser Wert wird jedes Mal inkrementiert, wenn die Nachricht anschließend erneut aus der Warteschlange entfernt wird.

Hinweis

Das DequeueCount Element wird nur im Antworttext zurückgegeben, wenn die Warteschlange mit Azure Queue Storage Version 2009-09-19 erstellt wurde.

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

Beispiel für eine Antwort

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>

Authorization

Dieser Vorgang kann durch den Kontobesitzer und von jedem Benutzer mit einer SAS (Shared Access Signature) ausgeführt werden, der über die Berechtigung zum Ausführen des Vorgangs verfügt.

Hinweise

Der Nachrichteninhalt wird in dem Format abgerufen, das für den Put Message-Vorgang verwendet wurde.

Wenn eine Nachricht aus der Warteschlange abgerufen wird, enthält die Antwort die Nachricht und einen Pop-Belegwert, der zum Löschen der Nachricht erforderlich ist. Die Nachricht wird nicht automatisch aus der Warteschlange gelöscht, aber nachdem sie abgerufen wurde, ist sie für andere Clients für das durch den visibilitytimeout Parameter angegebene Zeitintervall nicht sichtbar.

Wenn mehrere Nachrichten abgerufen werden, weist jede Nachricht eine zugeordnete Abrufbestätigung auf. Die maximale Anzahl von Nachrichten, die gleichzeitig abgerufen werden können, beträgt 32.

Vom Client, der die Nachricht abruft, wird erwartet, dass die Nachricht gelöscht wird, nachdem sie verarbeitet wurde und vor der Zeit, die TimeNextVisible vom -Element der Antwort angegeben wird, die basierend auf dem Wert des visibilitytimeout Parameters berechnet wird. Der Wert von visibilitytimeout wird dem Zeitpunkt hinzugefügt, zu dem die Nachricht abgerufen wird, um den Wert von TimeNextVisiblezu bestimmen.

Aufgrund von Uhrschiefe kann eine Nachricht, die mit einem bestimmten visibilitytimeout abgerufen wird, erneut angezeigt werden, bevor das angegebene Timeout abgelaufen ist. Beachten Sie, dass ein Client ableiten kann, dass eine Nachricht bereits von einem anderen Client entfernt wurde, basierend auf dem Pop-Beleg, der für jedes Entfernen einer Nachricht eindeutig ist. Wenn der Pop-Beleg eines Clients nicht mehr zum Löschen oder Aktualisieren einer Nachricht funktioniert und der Client den Fehler 404 (Nicht gefunden) empfängt, wurde die Nachricht von einem anderen Client aus der Warteschlange entfernt.

Wenn ein Consumer eine Nachricht über Get Messagesabruft, ist diese Nachricht in der Regel für das Löschen reserviert, bis das visibilitytimeout-Intervall abläuft. Dieses Verhalten ist jedoch nicht garantiert. Nach Ablauf des visibilitytimeout-Intervalls wird die Nachricht für andere Consumer wieder sichtbar. Wenn die Nachricht später nicht von einem anderen Consumer abgerufen und gelöscht wird, kann der ursprüngliche Consumer die Nachricht mithilfe des ursprünglichen Pop-Belegs löschen.

Beim erstmaligen Abrufen einer Nachricht wird ihre DequeueCount-Eigenschaft auf 1 festgelegt. Wenn sie nicht gelöscht und anschließend erneut abgerufen wird, wird die DequeueCount -Eigenschaft erhöht. Der Client bestimmt anhand dieses Werts möglicherweise, wie oft eine Nachricht abgerufen wurde.

Wenn sich der Parameter visibilitytimeout oder numofmessages außerhalb des Bereichs befindet, gibt der Dienst status Code 400 (Ungültige Anforderung) zusammen mit zusätzlichen Fehlerinformationen zurück, wie im folgenden Beispiel gezeigt.

  
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>

Weitere Informationen

Azure Queue Storage-Fehlercodes
Autorisieren von Anforderungen an Azure Storage
Status- und Fehlercodes