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:
| Metoda | Identyfikator URI żądania | Wersja PROTOKOŁU HTTP |
|---|---|---|
GET |
https://myaccount.queue.core.windows.net/myqueue/messages |
HTTP/1.1 |
Żą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:
| Metoda | Identyfikator URI żądania | Wersja PROTOKOŁU HTTP |
|---|---|---|
GET |
http://127.0.0.1:10001/devstoreaccount1/myqueue/messages |
HTTP/1.1 |
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.
| Parametr | Opis |
|---|---|
numofmessages |
Opcjonalny. Niezerowa wartość całkowita określająca liczbę komunikatów do pobrania z kolejki, maksymalnie 32. Jeśli jest widoczna mniejsza liczba komunikatów, zwracane są widoczne komunikaty. Domyślnie pojedynczy komunikat jest pobierany z kolejki przy użyciu tej operacji. |
visibilitytimeout |
Opcjonalny. Określa nową wartość limitu czasu widoczności w sekundach względem czasu serwera. Wartość domyślna to 30 sekund. Określona wartość musi być większa lub równa 1 sekundy i nie może być większa niż 7 dni lub większa niż 2 godziny w wersjach protokołu REST, które są wcześniejsze niż 2011-08-18. Limit czasu widoczności komunikatu można ustawić na wartość późniejszą niż czas wygaśnięcia. |
timeout |
Opcjonalny. Parametr jest wyrażony timeout w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Azure Queue Storage. |
Nagłówki żądań
W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.
| Nagłówek żądania | Opis |
|---|---|
Authorization |
Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage. |
Date lub x-ms-date |
Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage. |
x-ms-version |
Opcjonalny. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage. |
x-ms-client-request-id |
Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie usługi Azure Queue Storage. |
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.
| Nagłówek odpowiedzi | Opis |
|---|---|
x-ms-request-id |
Unikatowo identyfikuje wykonane żądanie i może służyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API. |
x-ms-version |
Wskazuje wersję usługi Azure Queue Storage użytą do wykonania żądania. Ten nagłówek jest zwracany w przypadku żądań wysyłanych w wersji 2009-09-19 lub nowszej. |
Date |
Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę zainicjowania odpowiedzi. |
x-ms-client-request-id |
Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli jest obecna w żądaniu, a wartość zawiera nie więcej niż 1024 widoczne znaki ASCII.
x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, nie będzie on obecny w odpowiedzi. |
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.
Uwaga
Element DequeueCount jest zwracany w treści odpowiedzi tylko wtedy, gdy kolejka została utworzona przy użyciu usługi Azure Queue Storage w wersji 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>
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