Obter Mensagens

Artigo
06/27/2023

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 InsertionTimeelementos , ExpirationTimee 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 Messagesde , 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

Partilhar via