Get Messages

Статья
06/27/2023

Операция Get Messages извлекает одно или несколько сообщений из передней части очереди.

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`GET`	`https://myaccount.queue.core.windows.net/myqueue/messages`	HTTP/1.1

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

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`GET`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages`	HTTP/1.1

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

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

В URI запроса могут быть заданы следующие дополнительные параметры.

Параметр	Описание
`numofmessages`	Необязательный элемент. Ненулевое целочисленное значение, которое определяет количество сообщений для получения из очереди (не более 32). Если отображается меньше сообщений, возвращаются видимые сообщения. По умолчанию эта операция возвращает одно сообщение из очереди.
`visibilitytimeout`	Необязательный элемент. Задает новое значение времени ожидания видимости (в секундах) относительно времени сервера. Значение по умолчанию - 30 секунды. Указанное значение должно быть больше или равно 1 секунде и не может превышать 7 дней или больше 2 часов в версиях протоколов REST, которые ранее 2011-08-18. Время ожидания видимости сообщения может быть задано позднее времени истечения срока действия.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в статье Настройка времени ожидания для операций хранилища очередей Azure.

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

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

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

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

Нет.

Ответ

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

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

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

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

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

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

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

Текст ответа

XML ответа для операции Get Messages возвращается в следующем формате.

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

Элементы InsertionTime, ExpirationTime и TimeNextVisible представляются в виде значений UTC и форматируются согласно RFC 1123.

Элемент DequeueCount имеет значение 1 при первом выведении сообщения из очереди. Это значение увеличивается при каждом последующем выведении сообщения из очереди.

Примечание

Элемент DequeueCount возвращается в тексте ответа, только если очередь была создана с помощью хранилища очередей Azure версии 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>

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

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>

Авторизация

Эта операция может выполняться владельцем учетной записи, а также любым пользователем с подписью общего доступа, у которой имеется разрешение на выполнение данной операции.

Когда сообщение извлекается из очереди, ответ включает в себя сообщение и значение подтверждения получения, необходимое для удаления очереди. Сообщение не удаляется из очереди автоматически, но после его извлечения оно не отображается другим клиентам в течение интервала времени, указанного visibilitytimeout параметром .

При получении нескольких сообщений каждое сообщение имеет соответствующее подтверждение. Максимальное количество сообщений, которые могут быть получены одновременно, составляет 32.

Клиент, извлекающий сообщение, должен удалить сообщение после его обработки и до времени, указанного элементом TimeNextVisible ответа, которое вычисляется на основе значения visibilitytimeout параметра . Значение visibilitytimeout добавляется к моменту извлечения сообщения, чтобы определить значение TimeNextVisible.

Из-за неравномерного распределения часов сообщение, полученное с определенным visibilitytimeout , может появиться до истечения указанного времени ожидания. Обратите внимание, что клиент может определить, что сообщение уже было выведено из очереди другим клиентом на основе всплывающего уведомления, которое является уникальным для каждого вывода сообщения из очереди. Если всплывающее уведомление клиента больше не работает для удаления или обновления сообщения, а клиент получает ошибку 404 (Не найдено), сообщение было выведено из очереди другим клиентом.

Как правило, когда потребитель получает сообщение через Get Messages, это сообщение резервируется для удаления до истечения интервала видимостиtimeout . Но такое поведение не гарантируется. После истечения интервала visibilitytimeout сообщение снова становится видимым для других потребителей. Если сообщение не будет впоследствии извлечено и удалено другим потребителем, исходный потребитель может удалить сообщение с помощью исходного всплывающего уведомления.

Если сообщение получено первый раз, то его свойство DequeueCount имеет значение 1. Если он не удаляется, а затем получается снова, DequeueCount свойство увеличивается. Клиент может использовать это значение, чтобы определить, сколько раз извлекалось сообщение.

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

  
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>

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

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

Поделиться через