Obter Mensagens
A Get Messages
operação obtém uma ou mais mensagens da frente da fila.
Pedir
O Get Messages
pedido pode ser construído da seguinte forma. Recomendamos que utilize HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento e substitua myqueue
pelo nome da fila:
Método | URI do pedido | Versão HTTP |
---|---|---|
GET |
https://myaccount.queue.core.windows.net/myqueue/messages |
HTTP/1.1 |
Pedido de serviço de armazenamento emulado
Quando estiver a fazer um pedido relativamente ao serviço de armazenamento emulado, especifique o nome do anfitrião do emulador e a porta do Armazenamento de Filas do Azure como 127.0.0.1:10001
, seguido do nome da conta de armazenamento emulada:
Método | URI do pedido | Versão HTTP |
---|---|---|
GET |
http://127.0.0.1:10001/devstoreaccount1/myqueue/messages |
HTTP/1.1 |
Para obter mais informações, veja Utilizar o emulador do Azurite para o desenvolvimento local do Armazenamento do Azure.
Parâmetros do URI
Os seguintes parâmetros adicionais podem ser especificados no URI do pedido.
Parâmetro | Description |
---|---|
numofmessages |
Opcional. Um valor inteiro diferente de zero que especifica o número de mensagens a obter da fila, até um máximo de 32. Se menos mensagens estiverem visíveis, as mensagens visíveis são devolvidas. Por predefinição, é obtida uma única mensagem da fila com esta operação. |
visibilitytimeout |
Opcional. Especifica o novo valor de tempo limite de visibilidade, em segundos, em relação ao tempo do servidor. O valor predefinido é 30 segundos. Um valor especificado tem de ser maior ou igual a 1 segundo e não pode ser superior a 7 dias ou superior a 2 horas em versões do protocolo REST anteriores a 08-18 de 2011. O tempo limite de visibilidade de uma mensagem pode ser definido para um valor posterior ao tempo de expiração. |
timeout |
Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Set time-outs for Azure Queue Storage operations (Definir tempos limite para operações de Armazenamento de Filas do Azure). |
Cabeçalhos do pedido
A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.
Cabeçalho do pedido | Description |
---|---|
Authorization |
Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. |
Date ou x-ms-date |
Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. |
x-ms-version |
Opcional. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure. |
x-ms-client-request-id |
Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar o Armazenamento de Filas do Azure. |
Corpo do pedido
Nenhum.
Resposta
A resposta inclui um código de estado HTTP e um conjunto de cabeçalhos de resposta.
Código de estado
Uma operação bem-sucedida devolve o código de estado 200 (OK).
Para obter mais informações sobre códigos de estado, veja Códigos de estado e de erro.
Cabeçalhos de resposta
A resposta para esta operação inclui os seguintes cabeçalhos. A resposta também pode incluir cabeçalhos HTTP padrão 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 o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API. |
x-ms-version |
Indica a versão do Armazenamento de Filas do Azure que foi utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos efetuados 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 utilizado para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho se estiver presente no pedido e o valor não contiver mais de 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, não estará presente na resposta. |
Corpo da resposta
O XML de resposta para a Get Messages
operação é devolvido no seguinte formato.
O MessageID
elemento é um valor GUID que identifica a mensagem na fila. Este valor é atribuído à mensagem pelo Armazenamento de Filas do Azure e é opaco para o cliente. Pode utilizar o valor juntamente com o valor do PopReceipt
elemento para eliminar uma mensagem da fila depois de a obter com a Get Messages
operação. O valor de PopReceipt
também é opaco para o cliente. A única finalidade é garantir que uma mensagem pode ser eliminada com a operação Eliminar Mensagem .
Os InsertionTime
elementos , ExpirationTime
e TimeNextVisible
são representados como valores UTC e formatados conforme descrito em RFC 1123.
O DequeueCount
elemento tem um valor de 1 na primeira vez que a mensagem é colocada em fila. Este valor é incrementado sempre que a mensagem é posteriormente colocada em fila.
Nota
O DequeueCount
elemento só é devolvido no corpo da resposta se a fila tiver sido criada com a versão 2009-09-19 do Armazenamento de Filas do Azure.
<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 amostra
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
Esta operação pode ser realizada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso partilhado que tenha permissão para efetuar esta operação.
Observações
O conteúdo da mensagem é obtido no formato utilizado para a operação Colocar Mensagem .
Quando uma mensagem é obtida da fila, a resposta inclui a mensagem e um valor de recibo pop, que é necessário para eliminar a mensagem. A mensagem não é eliminada automaticamente da fila, mas depois de ser obtida, não é visível para outros clientes para o intervalo de tempo especificado pelo visibilitytimeout
parâmetro .
Se forem obtidas várias mensagens, cada mensagem tem um recibo pop associado. O número máximo de mensagens que podem ser obtidas ao mesmo tempo é 32.
Espera-se que o cliente que obtém a mensagem elimine a mensagem depois de ter sido processada e antes do tempo especificado pelo TimeNextVisible
elemento da resposta, que é calculado com base no valor do visibilitytimeout
parâmetro. O valor de visibilitytimeout
é adicionado à hora em que a mensagem é obtida para determinar o valor de TimeNextVisible
.
Devido à distorção do relógio, uma mensagem obtida com um determinado visibilitytimeout
pode reaparecer antes de o tempo limite especificado ter decorrido. Tenha em atenção que um cliente pode inferir que uma mensagem já foi colocada em fila por um cliente diferente com base no recibo pop, que é exclusivo para cada colocação em fila de uma mensagem. Se o recibo pop de um cliente já não funcionar para eliminar ou atualizar uma mensagem e o cliente receber um erro 404 (Não Encontrado), a mensagem foi colocada em fila por outro cliente.
Normalmente, quando um consumidor obtém uma mensagem através Get Messages
de , essa mensagem é reservada para eliminação até que o intervalo de visibilidadetimeout expire. Mas este comportamento não é garantido. Após o intervalo de tempo limite de visibilidade expirar, a mensagem torna-se novamente visível para outros consumidores. Se a mensagem não for posteriormente obtida e eliminada por outro consumidor, o consumidor original pode eliminar a mensagem com o recibo pop original.
Quando uma mensagem é obtida pela primeira vez, a respetiva DequeueCount
propriedade é definida como 1. Se não for eliminado e for obtido novamente, a DequeueCount
propriedade será incrementada. O cliente pode utilizar este valor para determinar quantas vezes uma mensagem foi obtida.
Se o parâmetro visibilitytimeout ou numofmessages estiver fora do intervalo, o serviço devolve o código de estado 400 (Pedido Incorreto), juntamente com informações de erro adicionais, conforme mostrado no exemplo seguinte.
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>
Ver também
Códigos de erro do Armazenamento de Filas do Azure
Autorizar pedidos para o Armazenamento do Azure
Códigos de estado e de erro