Receber mensagens

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:

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:

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.

Cabeçalhos da solicitação

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

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.

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.

<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