Como repetir e limpar mensagens

As APIs de dados de assinantes do Pub/Sub, como pull, fornecem acesso limitado aos dados de mensagens. Normalmente, as mensagens confirmadas ficam inacessíveis para os assinantes. Além disso, os clientes assinantes precisam processar todas as mensagens de uma assinatura, mesmo que apenas um subconjunto seja necessário.

O recurso Busca amplia a funcionalidade de assinante, permitindo que você altere o estado de confirmação de mensagens em massa. Por exemplo, é possível repetir mensagens confirmadas anteriormente ou limpá-las em massa. Também é possível copiar o estado de uma assinatura em outra usando a busca em combinação com um Snapshot.

Esses recursos estão descritos abaixo. mas você pode ver um exemplo prático no guia de início rápido.

Como configurar a retenção de mensagens

Para procurar um horário no passado e repetir mensagens confirmadas anteriormente, é necessário configurar a retenção de mensagens no tópico ou configurar a assinatura para reter mensagens confirmadas.

Se a retenção de mensagens de tópico não estiver configurada, uma mensagem não confirmada será excluída da assinatura quando a idade exceder a propriedade message_retention_duration da assinatura. Por outro lado, se a retenção de mensagens de tópico estiver configurada, a mensagem não confirmada será excluída da assinatura somente quando a idade exceder o máximo do tópico e das message_retention_durations da assinatura.

Retenção de mensagens de tópico

Por padrão, um tópico do Pub/Sub descarta mensagens assim que são confirmadas por todas as assinaturas anexadas a ele. Configurar um tópico com retenção de mensagens oferece mais flexibilidade, permitindo que qualquer assinatura anexada ao tópico volte no tempo e reproduza as mensagens confirmadas anteriormente até o message_retention_duration do tópico. A retenção de mensagens de tópicos também permite que uma assinatura reproduza mensagens publicadas antes de você criar uma assinatura.

Um tópico pode reter mensagens publicadas por até 31 dias (configurável pela propriedade message_retention_duration do tópico), mesmo depois de elas serem confirmadas por todas as assinaturas anexadas. Nos casos em que o message_retention_duration do tópico é maior que o message_retention_duration da assinatura, o Pub/Sub descarta uma mensagem somente quando a idade excede o message_retention_duration do tópico.

Se a retenção de mensagens de tópico estiver ativada, os custos de armazenamento das mensagens retidas pelo tópico serão faturados no projeto do tópico.

Console

Para criar um tópico com a retenção de mensagens ativada, siga estas etapas:

  1. No console, acesse a página Tópicos do Pub/Sub.

    Acessar a página de tópicos

  2. Clique em Criar tópico.

  3. No campo Código do tópico, insira um código para o tópico.

  4. Marque a caixa ao lado de Definir a duração da retenção de mensagens. Não altere as outras opções.

  5. Use os menus suspensos abaixo de Duração da retenção de mensagens para selecionar o número de dias, horas e minutos para reter mensagens.

  6. Clique em Criar tópico para salvar o tópico.

Para atualizar as configurações de retenção de mensagens de um tópico:

  1. Selecione o tópico na página Tópicos do Pub/Sub.

    Acessar a página de tópicos

  2. Clique em Editar também na parte superior da página de detalhes do tópico.

  3. Ajuste o tempo de retenção ou ative/desative a retenção de mensagens marcando ou desmarcando a caixa Ativar retenção de mensagens.

  4. Clique em Atualizar para salvar as alterações no tópico.

gcloud

Para criar um tópico com uma duração de retenção de mensagem de sete dias, use o seguinte comando gcloud pubsub topics create:

gcloud pubsub topics create TOPIC_ID --message-retention-duration=7d

É possível atualizar essa configuração usando gcloud pubsub topics update. Isso também permite ativar a retenção de mensagens em um tópico existente:

gcloud pubsub topics update TOPIC_ID --message-retention-duration=1d

Também é possível desativar a retenção de mensagens para um tópico com o comando update:

gcloud pubsub topics update TOPIC_ID --clear-message-retention-duration

Retenção de mensagens de assinatura

Por padrão, as assinaturas descartam as mensagens assim que são confirmadas. As mensagens não confirmadas são retidas por padrão por sete dias (configurável pela propriedade message_retention_duration da assinatura). A configuração de uma assinatura para reter mensagens confirmadas (usando a propriedade retain_acked_messages) permite repetir mensagens retidas anteriormente retidas pela assinatura. É possível configurar a retenção de mensagens por até sete dias em uma assinatura. Essa configuração é válida para mensagens confirmadas e não reconhecidas. No entanto, as mensagens podem ser retidas em uma assinatura por mais de sete dias se a duração da retenção de mensagens configurada no tópico for maior que sete dias.

Se uma assinatura for configurada para reter mensagens confirmadas, os custos de armazenamento das mensagens confirmadas retidas pela assinatura serão faturados no projeto da assinatura.

Console

Para criar uma assinatura com a retenção de mensagens visualizadas ativadas, siga estas etapas:

  1. No console, acesse a página Assinaturas do Pub/Sub.

    Acessar a página de assinaturas

  2. Clique em Criar assinatura.

  3. No campo ID da assinatura, insira um ID para a assinatura.

  4. Use os menus suspensos abaixo de Duração da retenção de mensagens para selecionar o número de dias, horas e minutos para reter mensagens.

  5. Marque a caixa de seleção Reter mensagens confirmadas. Não altere as outras opções.

  6. Clique em Criar assinatura para salvá-la.

Para atualizar as configurações de retenção de mensagens de uma assinatura:

  1. Selecione sua assinatura na página de Assinaturas do Pub/Sub.

    Acessar a página de assinaturas

  2. Clique em Editar também na parte superior da página de detalhes da assinatura.

  3. Ajuste a duração da retenção da mensagem ou ative/desative a retenção de mensagens visualizadas marcando ou desmarcando a caixa Reter mensagens confirmadas.

  4. Clique em Atualizar para salvar as mudanças na assinatura.

gcloud

Para criar uma assinatura com a retenção de mensagens visualizadas ativadas, use o seguinte comando gcloud pubsub subscriptions create:

gcloud pubsub subscriptions create SUBSCRIPTION_ID
    --retain-acked-messages=true
    --message-retention-duration=5d

É possível atualizar essa configuração usando gcloud pubsub subscriptions update. Isso também permite ativar a retenção de mensagens enviadas para uma assinatura existente:

gcloud pubsub subscriptions update SUBSCRIPTION_ID --message-retention-duration=1d

Também é possível desativar a retenção de mensagens visualizadas para uma assinatura com o comando update:

gcloud pubsub subscriptions update SUBSCRIPTION_ID --retain-acked-messages=false

Como buscar um carimbo de data/hora

A busca por um horário marca todas as mensagens recebidas pelo Pub/Sub antes e depois do horário de confirmação. Busque um horário no futuro para limpar mensagens. Para reproduzir e reprocessar mensagens confirmadas anteriormente, procure um horário no passado. O horário de publicação da mensagem é gerado pelos servidores do Pub/Sub. Consulte publishTime na referência da API. Essa abordagem é imprecisa pelos seguintes motivos:

  • Os relógios dos servidores do Pub/Sub podem ter diferenças.

  • O Pub/Sub precisa trabalhar com o horário de chegada da solicitação de publicação em vez de quando um evento ocorreu no sistema de origem.

Como buscar um instantâneo

O recurso "Snapshot" permite capturar o estado de confirmação de mensagens de uma assinatura. Depois que um snapshot é criado, ele retém:

  • todas as mensagens que não foram confirmadas na assinatura de origem no momento da criação do snapshot;

  • qualquer mensagem publicada no tópico a partir de então.

É possível repetir essas mensagens não confirmadas usando um snapshot para buscar qualquer assinatura do tópico.

Diferentemente da busca por um horário, não é preciso executar nenhuma configuração de assinatura especial para procurar um snapshot. Você só precisa criar o snapshot com antecedência. Por exemplo, é possível criar um snapshot ao implantar um novo código de assinante, caso precise se recuperar de confirmações inesperadas ou errôneas.

Os instantâneos expiram e são excluídos nos seguintes casos (o que ocorrer primeiro):

  • Quando eles completam sete dias de vida útil.
  • A mensagem mais antiga não confirmada no snapshot excede o message retention duration.

Por exemplo, considere um snapshot de uma assinatura com um backlog em que a mensagem não confirmada mais antiga tenha um dia. O snapshot expira depois de seis dias, em vez de sete. Esse cronograma é necessário para que os snapshots ofereçam fortes garantias de exibição pelo menos uma vez.

Consistência eventual

As operações de busca são estritamente consistentes em relação às garantias de entrega de mensagens. Isso significa que qualquer mensagem que não será confirmada com base na condição de busca terá a garantia de ser entregue depois que a operação de busca for bem-sucedida. No entanto, as mensagens entregues não se tornam instantaneamente consistentes com a operação de busca. Portanto, uma mensagem que foi publicada antes do carimbo de data/hora de busca ou que está confirmada em um snapshot pode ser entregue após a operação de busca. De certo modo, a entrega de mensagens funciona como um sistema de consistência posterior com relação à operação de busca. Pode levar até um minuto para que a operação tenha efeito total.

Busca com filtros

Você pode reproduzir mensagens novamente a partir de assinaturas com filtros. Se você buscar um carimbo de data/hora usando uma assinatura com um filtro, o serviço do Pub/Sub só reenviará as mensagens que corresponderem ao filtro.

Um snapshot de uma assinatura com um filtro contém as seguintes mensagens:

  • Todas as mensagens que são mais recentes que o snapshot, incluindo aquelas que não correspondem ao filtro.
  • Mensagens não confirmadas que são mais antigas do que o snapshot.

Se você buscar um snapshot usando uma assinatura com um filtro, o serviço do Pub/Sub só reenviará as mensagens no snapshot que corresponderem ao filtro da assinatura que faz a solicitação de busca.

Para mais informações sobre filtros, consulte Como filtrar mensagens.

Procurar tópicos com mensagens inativas

Se você buscar mensagens em uma assinatura com um tópico de mensagem inativa, o Pub/Sub definirá as tentativas de entrega como 0. As mensagens recebidas dessas assinaturas têm um campo que registra o número de tentativas de entrega.

Para mais informações sobre tópicos de mensagens inativas, consulte Como encaminhar para tópicos de mensagens inativas.

Procurar políticas de repetição

Se você buscar mensagens em uma assinatura com uma política de nova tentativa, o Pub/Sub redefinirá o atraso entre os seguintes itens:

  1. O prazo de confirmação expira ou o assinante envia uma confirmação negativa.
  2. O Pub/Sub reenvia a mensagem.

Para mais informações sobre políticas de nova tentativa, consulte Como usar políticas de nova tentativa.

Busca exatamente com uma entrega

Se você buscar mensagens em uma assinatura com exatamente uma entrega, o Pub/Sub reenviará as mensagens confirmadas anteriormente que estão qualificadas para entrega. Qualquer confirmação em uma entrega feita antes da operação de busca falhará. As operações de busca têm consistência posterior.

Para mais informações sobre políticas de novas tentativas, consulte Exatamente uma vez.

Casos de uso

  • Atualize o código do assinante com segurança. Uma preocupação com a implantação de um novo código de assinante é que o novo executável possa confirmar mensagens erroneamente, levando à perda delas. A incorporação de instantâneos no seu processo de implantação permite se recuperar de bugs no novo código do assinante.
  • Recupere-se de problemas inesperados do assinante. Se os problemas do assinante não estiverem associados a um evento de implantação específico, pode ser que você não tenha um instantâneo relevante. Nesse caso, se você tiver ativado a retenção de mensagens confirmadas para uma assinatura, buscar um horário no passado permitirá que você se recupere do erro.
  • Economize tempo e custo de processamento. Realize uma confirmação em massa em um grande backlog de mensagens que não são mais relevantes.
  • Teste o código do assinante em dados conhecidos. Ao testar o código do assinante quanto a desempenho e consistência, vale a pena usar os mesmos dados em todas as execuções. Os snapshots proporcionam dados consistentes com semântica forte. Além disso, os snapshots podem ser aplicados a qualquer assinatura de um determinado tópico, incluindo uma recém-criada.

A seguir

É possível usar o Pub/Sub com o Dataflow. No entanto, não recomendamos o acesso direto à busca do Pub/Sub a partir de um pipeline do Dataflow em execução. Para o fluxo de trabalho recomendado, consulte Como usar o Pub/Sub com o Dataflow.