Receber mensagens

Artigo
06/27/2023

A operação Get Messages recupera uma ou mais mensagens do início da fila.

Solicitação

A solicitação Get Messages pode ser criada da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento e substitua myqueue pelo nome da fila:

Método	URI da solicitação	Versão HTTP
`GET`	`https://myaccount.queue.core.windows.net/myqueue/messages`	HTTP/1.1

Solicitação de serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta do Armazenamento de Filas do Azure como 127.0.0.1:10001, seguido pelo nome da conta de armazenamento emulada:

Método	URI da solicitação	Versão HTTP
`GET`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages`	HTTP/1.1

Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Parâmetros do URI

Os seguintes parâmetros adicionais podem ser especificados no URI de solicitação.

Parâmetro	Descrição
`numofmessages`	Opcional. Um valor inteiro diferente de zero que especifica o número de mensagens a serem recuperadas da fila, até um máximo de 32. Se menos mensagens estiverem visíveis, as mensagens visíveis serão retornadas. Por padrão, uma única mensagem é recuperada da fila com essa operação.
`visibilitytimeout`	Opcional. Especifica o novo valor de tempo limite de visibilidade, em segundos, em relação ao tempo do servidor. O valor padrão é 30 segundos. Um valor especificado deve ser maior ou igual a 1 segundo e não pode ser maior que 7 dias ou maior que 2 horas em versões de protocolo REST anteriores a 2011-08-18. O tempo limite de visibilidade de uma mensagem pode ser definido como um valor posterior ao tempo de expiração.
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações do Armazenamento de Filas do Azure.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Opcional. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres kib (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar o Armazenamento de Filas do Azure.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK).

Para obter mais informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta	Descrição
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
`x-ms-version`	Indica a versão do Armazenamento de Filas do Azure que foi usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e posterior.
`Date`	Um valor de data/hora UTC gerado pelo serviço, que indica a hora em que a resposta foi iniciada.
`x-ms-client-request-id`	Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do `x-ms-client-request-id` cabeçalho se ele estiver presente na solicitação e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, ele não estará presente na resposta.

Corpo da resposta

A resposta XML para a operação Get Messages é retornada no formato a seguir.

O elemento MessageID é um valor de GUID que identifica a mensagem na fila. Esse valor é atribuído à mensagem pelo Armazenamento de Filas do Azure e é opaco para o cliente. Você pode usar o valor junto com o valor do PopReceipt elemento para excluir uma mensagem da fila depois de recuperá-la usando a Get Messages operação . O valor de PopReceipt também é opaco para o cliente. Sua única finalidade é garantir que uma mensagem possa ser excluída com a operação Excluir Mensagem .

Os elementos InsertionTime, ExpirationTime e TimeNextVisible são representados como valores de UTC e formatados como descrito no RFC 1123.

O elemento DequeueCount tem um valor de 1 na primeira vez em que a mensagem é removida da fila. Esse valor é incrementado toda vez que a mensagem é removida da fila subsequentemente.

Observação

O DequeueCount elemento será retornado no corpo da resposta somente se a fila tiver sido criada usando o Armazenamento de Filas do Azure versão 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>

Resposta de exemplo

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>

Autorização

Essa operação poderá ser executada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para executar essa operação.

Comentários

O conteúdo da mensagem é recuperado no formato usado para a operação Colocar Mensagem .

Quando uma mensagem é recuperada da fila, a resposta inclui a mensagem e um valor de recebimento pop, que é necessário para excluir a mensagem. A mensagem não é excluída automaticamente da fila, mas depois de recuperada, ela não fica visível para outros clientes para o intervalo de tempo especificado pelo visibilitytimeout parâmetro .

Se várias mensagens forem recuperadas, cada mensagem terá um recebimento de mensagem pop-up associado. O número máximo de mensagens que podem ser recuperadas ao mesmo tempo é 32.

Espera-se que o cliente que recupera a mensagem exclua a mensagem após ela ter sido processada e antes da hora especificada pelo TimeNextVisible elemento da resposta, que é calculada com base no valor do visibilitytimeout parâmetro. O valor de visibilitytimeout é adicionado à hora em que a mensagem é recuperada para determinar o valor de TimeNextVisible.

Devido à distorção do relógio, uma mensagem recuperada com um determinado visibilitytimeout pode reaparecer antes que o tempo limite especificado tenha decorrido. Observe que um cliente pode inferir que uma mensagem já foi desativada por um cliente diferente com base no recibo pop, que é exclusivo para cada remoção de fila de uma mensagem. Se o recibo pop de um cliente não funcionar mais para excluir ou atualizar uma mensagem e o cliente receber um erro 404 (Não Encontrado), a mensagem será removida da fila por outro cliente.

Normalmente, quando um consumidor recupera uma mensagem por meio Get Messagesde , essa mensagem é reservada para exclusão até que o intervalo de tempo limite de visibilidade expire. Mas esse comportamento não é garantido. Depois que o intervalo de tempo limite de visibilidade expirar, a mensagem se tornará visível novamente para outros consumidores. Se a mensagem não for recuperada e excluída posteriormente por outro consumidor, o consumidor original poderá excluir a mensagem usando o recibo pop original.

Quando uma mensagem é recuperada pela primeira vez, sua propriedade DequeueCount é definida como 1. Se ele não for excluído e for recuperado posteriormente, a DequeueCount propriedade será incrementada. O cliente poderá usar esse valor para determinar quantas vezes uma mensagem foi recuperada.

Se o parâmetro visibilitytimeout ou numofmessages estiver fora do intervalo, o serviço retornará status código 400 (Solicitação Inválida), juntamente com informações de erro adicionais, conforme mostrado no exemplo a seguir.

  
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>

Confira também

Códigos de erro do Armazenamento de Filas do Azure
Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro