Umieść wiadomość

Artykuł
08/04/2023

Operacja Put Message dodaje nowy komunikat z tyłu kolejki komunikatów. Można również określić limit czasu widoczności, aby komunikat był niewidoczny do momentu wygaśnięcia limitu czasu widoczności. Komunikat musi być w formacie, który można uwzględnić w żądaniu XML z kodowaniem UTF-8. Zakodowany komunikat może mieć rozmiar do 64 kibibajtów (KiB) w wersji 2011-08-18 lub nowszej lub 8 KiB dla starszych wersji.

Żądanie

Żądanie można skonstruować Put Message w następujący sposób. Zalecamy używanie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu i myqueue nazwą kolejki:

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
`POST`	`https://myaccount.queue.core.windows.net/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1

Żądanie usługi magazynu emulowanego

Podczas wysyłania żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i port magazynu kolejki jako 127.0.0.1:10001, a następnie nazwę emulowanego konta magazynu:

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
`POST`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	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 parametry:

Parametr	Opis
`visibilitytimeout=<int=seconds>`	Opcjonalny. Określa nową wartość limitu czasu widoczności w sekundach względem czasu serwera. Jeśli jest określony, żądanie musi zostać wykonane przy użyciu `x-ms-version` 2011-08-18 lub nowszego. Jeśli nie zostanie określona, wartość domyślna to 0. Nowa wartość musi być większa lub równa 0 i nie może być większa niż 7 dni. Nie można ustawić limitu czasu widoczności komunikatu na wartość późniejszą niż data wygaśnięcia. Ustaw `visibilitytimeout` wartość mniejszą niż wartość czasu wygaśnięcia.
`messagettl=<int-seconds>`	Opcjonalny. Określa interwał czasu wygaśnięcia komunikatu w sekundach. W wersjach starszych niż 2017-07-29 maksymalny dozwolony czas wygaśnięcia wynosi 7 dni. W przypadku wersji 2017-07-29 i nowszej maksymalny czas wygaśnięcia może być dowolną liczbą dodatnią i `-1`, co oznacza, że komunikat nie wygaśnie. Jeśli ten parametr zostanie pominięty, domyślny czas wygaśnięcia wynosi 7 dni.
`timeout`	Opcjonalny. Parametr jest wyrażony `timeout` w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi kolejki.

Nagłówki żądań

Wymagane i opcjonalne nagłówki żądań opisano w poniższej tabeli:

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` `or 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 usług Azure Storage.
`x-ms-client-request-id`	Opcjonalny. Udostępnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer.

Treść żądania

Treść żądania zawiera dane komunikatu w następującym formacie XML. Należy pamiętać, że zawartość komunikatu musi być w formacie, który może być zakodowany przy użyciu protokołu UTF-8.

<QueueMessage>  
    <MessageText>message-content</MessageText>  
</QueueMessage>

Przykładowe żądanie

Request:  
POST https://myaccount.queue.core.windows.net/messages?visibilitytimeout=30&timeout=30 HTTP/1.1  
  
Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Tue, 30 Aug 2011 01:03:21 GMT  
Authorization: SharedKey myaccount:sr8rIheJmCd6npMSx7DfAY3L//V3uWvSXOzUBCV9wnk=  
Content-Length: 100  
  
Body:  
<QueueMessage>  
<MessageText>PHNhbXBsZT5zYW1wbGUgbWVzc2FnZTwvc2FtcGxlPg==</MessageText>  
</QueueMessage>

Reakcja

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

Kod stanu

Operacja zakończona powodzeniem zwraca kod stanu 201 (utworzono).

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 nagłówki standardowe są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek żądania	Opis
`x-ms-request-id`	Unikatowo identyfikuje wykonane żądanie i można go 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 kolejki, która została użyta do wykonania żądania. Ten nagłówek jest zwracany dla żądań, które zostały wykonane 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`	Ten nagłówek może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości `x-ms-client-request-id` nagłówka, jeśli znajduje się w żądaniu, a wartość nie zawiera więcej niż 1024 widocznych znaków ASCII. `x-ms-client-request-id` Jeśli nagłówek nie jest obecny w żądaniu, nie będzie on obecny w odpowiedzi.

Treść odpowiedzi

Od wersji 2016-05-31 odpowiedź dla Put Message operacji zawiera informacje o komunikacie w treści odpowiedzi. Format XML zwracanej treści jest opisany tutaj.

Element MessageID jest wartością identyfikatora GUID, która identyfikuje komunikat w kolejce. Ta wartość jest przypisywana do komunikatu przez usługę Queue Storage i jest nieprzezroczysta dla klienta. Ta wartość może być używana razem z wartością elementu PopReceipt w celu usunięcia lub zaktualizowania komunikatu z kolejki. Wartość PopReceipt jest również nieprzezroczysty dla klienta i jest wymagana, gdy używasz interfejsów API usuwania komunikatu lub aktualizowania komunikatów.

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

<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>
    </QueueMessage>
</QueueMessagesList>

Przykładowa odpowiedź

Response Status:
HTTP/1.1 200 OK
Response headers:
Transfer-Encoding: chunked
Content-Type: application/xml
x-ms-version: 2016-05-31
Date: Fri, 09 Oct 2016 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 2016 21:04:30 GMT</InsertionTime>
    <ExpirationTime>Fri, 16 Oct 2016 21:04:30 GMT</ExpirationTime>
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>
    <TimeNextVisible>Fri, 09 Oct 2016 23:29:20 GMT</TimeNextVisible>
   </QueueMessage>
</QueueMessagesList>

Autoryzacja

Ta operacja może być wykonywana przez właściciela konta i przez każdego, kto ma sygnaturę dostępu współdzielonego z uprawnieniami do wykonania tej operacji.

Uwagi

Opcjonalny limit czasu widoczności określa czas niewidoczny dla komunikatu. Po wygaśnięciu limitu czasu komunikat staje się widoczny. Jeśli nie określisz limitu czasu widoczności, zostanie użyta domyślna wartość 0.

Opcjonalny czas wygaśnięcia komunikatu określa, jak długo komunikat pozostaje w kolejce. Komunikat zostanie usunięty z kolejki po wygaśnięciu okresu wygaśnięcia.

Komunikat musi być w formacie, który można uwzględnić w żądaniu XML z kodowaniem UTF-8. Aby dołączyć znaczniki w komunikacie, zawartość wiadomości musi być kodowana przy użyciu kodu XML lub Base64. Wszelkie znaczniki XML w komunikacie, który nie został uniknięty lub zakodowany, zostanie usunięty przed dodaniu komunikatu do kolejki.

Jeśli komunikat jest za duży, usługa zwraca kod stanu 400 (Nieprawidłowe żądanie).

Zobacz też

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