Nachrichten abrufen

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:

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:

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.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

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.

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.

<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