Сообщение Put

Статья
06/27/2023

Операция Put Message добавляет новое сообщение в конец очереди сообщений. Также можно указать время ожидания видимости, чтобы сделать сообщение невидимым до истечения времени ожидания видимости. Сообщение должно быть в формате, который может включаться в XML-запрос с кодировкой UTF-8. Размер закодированного сообщения может составлять до 64 киб (КиБ) для версии 2011-08-18 и более поздних версий или 8 КиБ для более ранних версий.

Запрос

Запрос можно создать Put Message следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS. Замените myaccount именем вашей учетной записи хранения, а myqueue — именем очереди:

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`POST`	`https://myaccount.queue.core.windows.net/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1

Запрос службы эмулированного хранилища

При выполнении запроса к эмулированной службе хранилища укажите имя узла эмулятора и порт хранилища очередей в качестве 127.0.0.1:10001, а затем имя эмулированной учетной записи хранения:

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`POST`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1

Дополнительные сведения см. в статье Использование эмулятора Azurite для разработки и тестирования службы хранилища Azure.

Параметры универсального кода ресурса (URI)

В URI запроса можно указать следующие параметры:

Параметр	Описание
`visibilitytimeout=<int=seconds>`	Необязательный элемент. Указывает новое значение времени ожидания видимости в секундах относительно времени сервера. Если он указан, запрос должен быть выполнен с помощью `x-ms-version` 18-08.2011 или более поздней версии. Если он не указан, значение по умолчанию равно 0. Новое значение должно быть больше или равно 0 и не может превышать 7 дней. Для времени ожидания видимости сообщения нельзя задать значение, которое позже даты окончания срока действия. Задайте `visibilitytimeout` значение, меньшее значения срока жизни.
`messagettl=<int-seconds>`	Необязательный элемент. Задает интервал срока существования сообщения в секундах. В версиях, предшествующих 29.07.2017, максимально допустимое время жизни составляет 7 дней. Для версии 2017-07-29 и более поздних максимальное время жизни может быть любым положительным числом, а `-1`также значением , которое указывает на то, что срок действия сообщения не истекает. Если этот параметр пропущен, по умолчанию срок существования составляет 7 дней.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций службы очередей.

Заголовки запросов

Обязательные и необязательные заголовки запросов описаны в следующей таблице:

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` `or x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Необязательный элемент. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером.

Текст запроса

Текст запроса содержит данные сообщения в следующем формате XML. Обратите внимание, что содержимое сообщения должно быть в формате, который можно закодировать с помощью UTF-8.

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

Пример запроса

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>

Ответ

Ответ включает код состояния HTTP и набор заголовков ответа.

Код состояния

Успешная операция возвращает код состояния 201 (создано).

Дополнительные сведения о кодах состояния см. в разделе Коды состояния и ошибок.

Заголовки ответов

Ответ для этой операции включает следующие заголовки. Ответ может также включать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.

Заголовок запроса	Описание
`x-ms-request-id`	Уникально идентифицирует выполненный запрос, и его можно использовать для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
`x-ms-version`	Указывает версию службы очередей, которая использовалась для выполнения запроса. Этот заголовок возвращается для запросов, выполненных в отношении версии 2009-09-19 и более поздних версий.
`Date`	Значение даты и времени в формате UTC, созданное службой, указывающее время, когда был инициирован ответ.
`x-ms-client-request-id`	Этот заголовок можно использовать для устранения неполадок с запросами и соответствующими ответами. Значение этого заголовка равно значению заголовка `x-ms-client-request-id` , если он присутствует в запросе и содержит не более 1024 видимых символов ASCII. Если заголовок `x-ms-client-request-id` отсутствует в запросе, он не будет присутствовать в ответе.

Текст ответа

Начиная с версии 2016-05-31, ответ для Put Message операции содержит сведения о сообщении в тексте ответа. Формат XML возвращаемого текста описан здесь.

Элемент MessageID является значением GUID, которое идентифицирует сообщение в очереди. Это значение присваивается сообщению хранилищем очередей и непрозрачно для клиента. Это значение можно использовать вместе со значением элемента PopReceipt для удаления или обновления сообщения из очереди. Значение PopReceipt также является непрозрачным для клиента и требуется при использовании API удаления сообщения или обновления сообщения.

Элементы InsertionTime, ExpirationTime и TimeNextVisible представляются в виде значений UTC и форматируются согласно 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>

Пример ответа

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>

Авторизация

Эту операцию может выполнить владелец учетной записи и любой пользователь с подписанным URL-адресом с разрешениями на выполнение этой операции.

Необязательный тайм-аут видимости указывает время, когда сообщение невидимо. По истечении времени ожидания сообщение становится видимым. Если не указать время ожидания видимости, используется значение по умолчанию 0.

Необязательный срок жизни сообщения указывает, как долго сообщение остается в очереди. Сообщение удаляется из очереди по истечении срока жизни.

Сообщение должно быть в формате, который может включаться в XML-запрос с кодировкой UTF-8. Для включения в сообщение разметки содержимое сообщения должно быть либо экранировано XML-тегами, либо иметь кодировку Base64. Любая xml-разметка в сообщении, которая не экранирована или не закодирована, удаляется перед добавлением сообщения в очередь.

Если сообщение слишком большое, служба возвращает код состояния 400 (неправильный запрос).

См. также раздел

Авторизация запросов к службе хранилища Azure
Коды состояний и ошибок
Коды ошибок службы очередей