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:
| 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