Inspecionar Mensagens

  • Artigo

A Peek Messages operação recupera uma ou mais mensagens da frente da fila, mas não altera a visibilidade da mensagem.

Solicitação

Você pode construir a solicitação da Peek Messages 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?peekonly=true 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 serviço Fila 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?peekonly=true 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 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 inspecionadas da fila, até um máximo de 32. Por padrão, uma única mensagem é inspecionada da fila com essa operação.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de serviço fila.

Cabeçalhos da solicitação

Os cabeçalhos de solicitação obrigatórios e opcionais são descritos na tabela a seguir:

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, um conjunto de cabeçalhos de resposta XML e um corpo 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 inclui 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 você pode usá-la para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
x-ms-version A versão do serviço Fila usada para executar a solicitação. Retornado para solicitações que foram 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 suas 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 Peek 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 serviço Fila e é opaco ao cliente.

Os elementos InsertionTime e ExpirationTime 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 com o serviço Queue versão 2009-09-19.

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>

Observação

Essa resposta difere da resposta da operação Obter Mensagens , pois ela não contém os PopReceipt elementos ou TimeNextVisible .

Resposta de exemplo

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Fri, 16 Sep 2011 22:51:18 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
  
Response Body:  
<?xml version="1.0" encoding="utf-8"?>  
<QueueMessagesList>  
  <QueueMessage>  
    <MessageId>06eba214-8107-4412-a7f6-710a9baff647</MessageId>  
    <InsertionTime>Fri, 09 Oct 2009 18:59:54 GMT</InsertionTime>  
    <ExpirationTime>Fri, 16 Sep 2009 18:59:54 GMT</ExpirationTime>  
    <DequeueCount>1</DequeueCount>  
    <MessageText>PHRlc3Q+dGhpcyBpcyBhIHRlc3QgbWVzc2FnZTwvdGVzdD4=</MessageText>  
  </QueueMessage>  
</QueueMessagesList>

Autorização

Essa operação pode 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

Quando uma mensagem é recuperada de fila com peekonly definido como true, a visibilidade da mensagem permanece inalterada. A mensagem permanece disponível para outros consumidores da fila até que um cliente recupere a mensagem usando a operação Obter Mensagens . O cliente que solicita a mensagem não recebe um recibo pop com a resposta e, portanto, não pode excluir a mensagem.

Somente as mensagens visíveis podem ser recuperadas com a Peek Messages operação. Observe que o número máximo de mensagens que podem ser recuperadas é 32.

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

Observação

Uma chamada para Peek Messages não incrementa o valor de DequeueCount, mas retorna esse valor para o cliente ler.

Se o parâmetro numofmessages estiver fora do intervalo, o serviço retornará status código 400 (Solicitação Incorreta), 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

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