Pobieranie komunikatów

Operacja Get Messages pobiera jeden lub więcej komunikatów z przodu kolejki.

Żądanie

Żądanie Get Messages może być skonstruowane w następujący sposób. Zalecamy korzystanie z protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu i zastąp myqueue ciąg nazwą kolejki:

Żądanie usługi magazynu emulowanego

Gdy wysyłasz żądanie względem emulowanej usługi magazynu, określ nazwę hosta emulatora i port usługi Azure Queue Storage jako 127.0.0.1:10001, a następnie nazwę emulowanego konta magazynu:

Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Parametry identyfikatora URI

Dla identyfikatora URI żądania można określić następujące dodatkowe parametry.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Treść żądania

Brak.

Reakcja

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.

Kod stanu

Pomyślna operacja zwraca kod stanu 200 (OK).

Aby uzyskać więcej informacji na temat kodów stanu, zobacz Kody stanu i błędów.

Nagłówki odpowiedzi

Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Treść odpowiedzi

Kod XML odpowiedzi dla Get Messages operacji jest zwracany w następującym formacie.

Element MessageID jest wartością identyfikatora GUID, która identyfikuje komunikat w kolejce. Ta wartość jest przypisywana do komunikatu przez usługę Azure Queue Storage i jest nieprzezroczysta dla klienta. Możesz użyć wartości wraz z wartością PopReceipt elementu, aby usunąć komunikat z kolejki po pobraniu go przy użyciu Get Messages operacji . Wartość PopReceipt jest również nieprzezroczysta dla klienta. Jego jedynym celem jest upewnienie się, że komunikat można usunąć za pomocą operacji Usuń komunikat .

InsertionTimeElementy , ExpirationTimei TimeNextVisible są reprezentowane jako wartości UTC i sformatowane zgodnie z opisem w dokumentach RFC 1123.

Element DequeueCount ma wartość 1 przy pierwszym dequeued komunikatu. Ta wartość jest zwiększana za każdym razem, gdy komunikat zostanie odsunięty w kolejce.

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

Przykładowa odpowiedź

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>  

Autoryzacja

Tę operację może wykonać właściciel konta i każdy, kto ma sygnaturę dostępu współdzielonego, która ma uprawnienia do wykonania tej operacji.

Uwagi

Zawartość komunikatu jest pobierana w formacie, który został użyty do operacji Put Message .

Po pobraniu komunikatu z kolejki odpowiedź zawiera komunikat i wartość potwierdzenia wyskakującego, która jest wymagana do usunięcia komunikatu. Komunikat nie jest automatycznie usuwany z kolejki, ale po jego pobraniu nie jest widoczny dla innych klientów dla interwału czasu określonego visibilitytimeout przez parametr .

Jeśli zostanie pobranych wiele wiadomości, każda wiadomość ma skojarzone potwierdzenie wyskakujące. Maksymalna liczba komunikatów, które mogą być pobierane w tym samym czasie, wynosi 32.

Klient, który pobiera komunikat, powinien usunąć komunikat po jego przetworzeniu i przed upływem czasu określonego przez TimeNextVisible element odpowiedzi, który jest obliczany na podstawie wartości parametru visibilitytimeout . Wartość elementu visibilitytimeout jest dodawana do czasu pobrania komunikatu w celu określenia wartości TimeNextVisible.

Ze względu na niesymetryczność zegara komunikat pobrany z określonym visibilitytimeout czasem może pojawić się ponownie przed upływem określonego limitu czasu. Należy pamiętać, że klient może wywnioskować, że komunikat został już odsunięty od kolejki przez innego klienta na podstawie potwierdzenia podręcznego, który jest unikatowy dla każdego usuwania komunikatu z kolejki. Jeśli potwierdzenie podręczne klienta nie działa już w celu usunięcia lub zaktualizowania komunikatu, a klient otrzyma błąd 404 (Nie znaleziono), komunikat został usunięty z kolejki przez innego klienta.

Zazwyczaj gdy użytkownik pobiera komunikat za pośrednictwem Get Messageselementu , ten komunikat jest zarezerwowany do usunięcia do momentu wygaśnięcia interwału czasu widoczności . Ale to zachowanie nie jest gwarantowane. Po wygaśnięciu interwału widoczności komunikat ponownie stanie się widoczny dla innych użytkowników. Jeśli wiadomość nie zostanie później pobrana i usunięta przez innego konsumenta, oryginalny odbiorca może usunąć wiadomość przy użyciu oryginalnego potwierdzenia podręcznego.

Gdy komunikat zostanie pobrany po raz pierwszy, jego DequeueCount właściwość jest ustawiona na 1. Jeśli nie zostanie usunięty, a następnie zostanie on pobrany ponownie, DequeueCount właściwość jest zwiększana. Klient może użyć tej wartości, aby określić, ile razy został pobrany komunikat.

Jeśli parametr visibilitytimeout lub numofmessages jest poza zakresem, usługa zwraca kod stanu 400 (nieprawidłowe żądanie) wraz z dodatkowymi informacjami o błędzie, jak pokazano w poniższym przykładzie.

  
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>  
  

Zobacz też

Kody błędów usługi Azure Queue Storage
Autoryzowanie żądań do usługi Azure Storage
Kody stanu i błędów