Atualização de mensagem

  • Artigo

A operação Update Message atualiza o tempo limite de visibilidade de uma mensagem. Você também pode usar essa operação para atualizar o conteúdo de uma mensagem. Uma mensagem deve estar em um formato que possa ser incluído em uma solicitação XML com codificação UTF-8, e a mensagem codificada pode ter até 64 KB de tamanho. Essa operação foi introduzida com a versão 2011-08-18 da API de Armazenamento de Filas do Azure.

Solicitação

Você pode construir a solicitação da Update Message seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento e myqueue pelo nome da fila.

Método URI da solicitação Versão HTTP
PUT https://myaccount.queue.core.windows.net/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds> HTTP/1.1

Serviço de armazenamento emulado

Essa operação tem suporte para o SDK 1.6 e versões posteriores.

Quando você fizer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta de Armazenamento de Filas como 127.0.0.1:10001, seguido pelo nome da conta de armazenamento emulado.

Método URI da solicitação Versão HTTP
PUT http://127.0.0.1:10001/devstoreaccount1/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds> HTTP/1.1

Parâmetros do URI

Você pode especificar os seguintes parâmetros no URI de solicitação.

Parâmetro Descrição
popreceipt Obrigatórios. Especifica o valor de recibo pop válido retornado de uma chamada anterior para as operações Obter Mensagens ou Atualizar Mensagem . O popreceipt deve ser codificado em URL.
visibilitytimeout Obrigatórios. Especifica o novo valor de tempo limite de visibilidade, em segundos, em relação à hora do servidor. O novo valor deve ser maior ou igual a 0 e não pode ser maior que 7 dias. O tempo limite de visibilidade de uma mensagem não pode ser definido como um valor posterior ao tempo de expiração. Você pode atualizar uma mensagem até que ela tenha sido excluída ou expirada.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Armazenamento de Filas.

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 or 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 Requer 2011-08-18 ou posterior. 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

O corpo da solicitação contém os dados da mensagem no seguinte formato XML. Observe que o conteúdo da mensagem deve estar em um formato que possa ser codificado com UTF-8.

<QueueMessage>  
    <MessageText>message-content</MessageText>  
</QueueMessage>

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 204 (Sem conteúdo). Para obter 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 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 da solicitação Descrição
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
x-ms-version Indica a versão do Armazenamento de Filas usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
Date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
x-ms-popreceipt O recebimento de mensagem pop-up de mensagem da fila.
x-ms-time-next-visible Um valor de data/hora UTC que demonstra quando a mensagem se tornará visível na fila.
x-ms-client-request-id Você pode usar esse cabeçalho para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se ele estiver presente na solicitação. O valor é no máximo 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo da resposta

Nenhum.

Autorização

O proprietário da conta pode executar essa operação. Além disso, qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para executar essa operação pode fazer isso.

Exemplo de solicitação e resposta

A solicitação a seguir prorroga a visibilidade de uma mensagem da fila em 30 segundos e atualiza seu conteúdo.

PUT https://myaccount.queue.core.windows.net/myqueue/messages/663d89aa-d1d9-42a2-9a6a-fcf822a97d2c?popreceipt=AgAAAAEAAAApAAAAGIw6Q29bzAE%3d&visibilitytimeout=30&timeout=30 HTTP/1.1

A solicitação é enviada com os seguintes cabeçalhos:

x-ms-version: 2011-08-18  
x-ms-date: Mon, 29 Aug 2011 17:17:21 GMT  
Authorization: SharedKey myaccount:batcrWZ35InGCZeTUFWMdIQiOZPCW7UEyeGdDOg7WW4=  
Content-Length: 75

A solicitação é enviada com o seguinte corpo XML:

<QueueMessage>  
    <MessageText>new-message-content</MessageText>  
</QueueMessage>

Depois que a solicitação tiver sido enviada, a resposta a seguir será retornada:

HTTP/1.1 204 No Content  
Content-Length: 0  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: df34a7dd-3cbe-4206-a586-d6de3cf225a7  
x-ms-version: 2011-08-18  
x-ms-popreceipt: AwAAAAIAAAApAAAAINtMQ29bzAEBAAAA  
x-ms-time-next-visible: Mon, 29 Aug 2011 17:17:51 GMT  
Date: Mon, 29 Aug 2011 17:17:21 GMT

Comentários

Uma Update Message operação falhará se a mensagem especificada não existir na fila ou se o recibo pop especificado não corresponder à mensagem.

Um recebimento de mensagem pop-up será retornado pela operação Get Messages ou Update Message. Os recebimentos de mensagem pop-up permanecem válidos até que um dos seguintes eventos ocorra:

  • A mensagem expirou.

  • A mensagem foi excluída usando o último recibo pop recebido, seja de Get Messages ou Update Message.

  • O tempo de invisibilidade expirou, e a mensagem foi removida da fila por uma solicitação Get Messages. Quando o tempo de invisibilidade expira, a mensagem se torna visível novamente. Se ele for recuperado por outra Get Messages solicitação, o recibo pop retornado poderá ser usado para excluir ou atualizar a mensagem.

  • A mensagem foi atualizada com um novo tempo limite da visibilidade. Quando a mensagem for atualizada, um novo recebimento de mensagem pop-up será retornado.

Você pode usar a Update Message operação para estender continuamente a invisibilidade de uma mensagem de fila. Essa funcionalidade pode ser útil se você quiser que uma função de trabalho aluge uma mensagem de fila. Por exemplo, se uma função de trabalho chamar Obter Mensagens e reconhecer que precisa de mais tempo para processar uma mensagem, ela poderá estender continuamente a invisibilidade da mensagem até que ela seja processada. Se a função de trabalho falhasse durante o processamento, eventualmente a mensagem se tornaria visível novamente e outra função de trabalho poderia processá-la.

Confira também

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