Depois que você confirma mensagens no Pub/Sub, elas ficam inacessíveis ao cliente assinante. 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 os recursos do 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 confirmação de uma assinatura em outra usando a busca em combinação com um snapshot.
Para uma demonstração rápida de como esses recursos funcionam, consulte Repetir uma mensagem no Pub/Sub buscando um snapshot ou carimbo de data/hora.
Visão geral do snapshot e da busca
Um snapshot do Pub/Sub é uma visualização pontual, consistente e confiável do estado de confirmação de mensagem de uma assinatura. Um snapshot registra o estado de confirmação de todas as mensagens em uma assinatura no momento da criação. Um snapshot retém as mensagens não confirmadas da assinatura de origem no momento da criação do snapshot e todas as mensagens publicadas no tópico após a criação do snapshot.
A vida útil de um snapshot é determinada pelo backlog existente da assinatura de origem. A vida útil é igual a 7 dias menos a idade da mensagem não confirmada mais antiga na assinatura. 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 após 6 dias. Esse cronograma é necessário para que os snapshots ofereçam uma garantia de entrega pelo menos uma vez.
A vida útil máxima possível de um snapshot é de sete dias. Não é possível criar um snapshot que expire em menos de 1 hora após o momento da criação.
O recurso de busca permite procurar um snapshot ou carimbo de data/hora específico para uma assinatura. Esse recurso permite controlar como o Pub/Sub pode entregar mensagens de um ponto específico no tempo ou de um snapshot específico.
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. Para ver mais informações, consulte os seguintes tópicos:
Consistência posterior das operações de busca
As operações de busca são estritamente consistentes em relação à garantia de entrega de mensagens. Isso significa que qualquer mensagem que não seja confirmada com base na condição de busca terá garantia de ser entregue após a operação de busca ser realizada. 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 certa forma, a entrega de mensagens funciona como um sistema eventualmente consistente em relação à operação de busca. Pode levar até um minuto para que a operação tenha efeito total.
Casos de uso para operações de busca
- 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.
Criar um snapshot
É possível criar um snapshot usando o console, as APIs do Google ou a CLI do Google Cloud.
Console
Para criar um snapshot, siga estas etapas:
No Google Cloud console do, acesse a página Snapshots.
Clique em Criar snapshot.
Em Selecionar uma assinatura do Pub/Sub, selecione uma assinatura.
Em ID do snapshot, digite um nome para o snapshot.
Para mais informações sobre como nomear recursos do Pub/Sub, consulte Diretrizes para nomear um tópico, assinatura, esquema ou snapshot.
Clique em Criar para criar o snapshot.
Também é possível criar um snapshot na página Assinaturas. Se você criar um snapshot imediatamente após criar uma assinatura, poderá receber um erro devido ao atraso de propagação da assinatura recém-criada.
gcloud
Para criar um snapshot, use o
seguinte
gcloud pubsub snapshots create
comando:
gcloud pubsub snapshots create \ --project=PROJECT_ID \ --subscription=SUBSCRIPTION_ID \ SNAPSHOT_ID
Substitua:
PROJECT_ID. Especifica o ID do projeto.
SUBSCRIPTION_ID. Especifica o ID da assinatura.
SNAPSHOT_ID. Especifica o ID do snapshot.
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.
É possível realizar os seguintes tipos de operações de busca com base em carimbos de data/hora:
Para limpar todas as mensagens, busque um horário no futuro.
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.
É possível buscar um carimbo de data/hora usando o console, as APIs do Google ou a CLI do Google Cloud. Antes de buscar um carimbo de data/hora em uma assinatura, verifique se a retenção de mensagens está ativada na assinatura.
Console
Para buscar um carimbo de data/hora, siga estas etapas:
No Google Cloud console do, acesse a página Assinatura.
Clique em uma assinatura que tenha a retenção de mensagens ativada.
Na página de detalhes da assinatura, clique em Repetir mensagens.
Em Buscar, clique em Para um ponto anterior no tempo.
Selecione uma data e hora adequadas e clique em Buscar.
gcloud
Para buscar um carimbo de data/hora, use o
seguinte
gcloud pubsub subscriptions seek
comando:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \ --time=TIME \
Substitua:
- TIME: o horário em que você quer realizar a operação de busca.
- SUBSCRIPTION_ID: o ID da assinatura.
Para mais informações sobre formatos de tempo compatíveis, consulte gcloud topic datetimes.
Buscar um snapshot
É possível repetir 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.
Se o backlog na assinatura for muito antigo e o snapshot resultante expirar em menos de 1 hora, a operação de busca falhará.
É possível buscar um snapshot usando o console, as APIs do Google ou a CLI do Google Cloud.
Console
Para buscar um snapshot, siga estas etapas:
No Google Cloud console do, acesse a página Assinatura.
Clique em uma assinatura.
Na página de detalhes da assinatura, clique em Repetir mensagens.
Em Buscar, clique em Para um snapshot.
Selecione um snapshot adequado e clique em Buscar.
gcloud
Para buscar um snapshot, use o
seguinte
gcloud pubsub subscriptions seek
comando:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \ --snapshot=SNAPSHOT_ID
Substitua:
- SNAPSHOT_ID: o ID de um snapshot. O tópico do snapshot precisa ser o mesmo da assinatura.
- SUBSCRIPTION_ID: o ID da assinatura.
Buscar 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.
Buscar com tópicos de mensagens inativas
Se você buscar mensagens em uma assinatura com um tópico de mensagens inativas, 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.
Buscar com 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:
- O prazo de confirmação expira ou o assinante envia uma confirmação negativa.
- O Pub/Sub reenvia a mensagem.
Para mais informações sobre políticas de nova tentativa, consulte Como usar políticas de nova tentativa.
Buscar com entrega exatamente uma vez
Se você buscar mensagens em uma assinatura com entrega exatamente uma vez, o Pub/Sub reenviará as mensagens confirmadas anteriormente que são qualificadas para entrega. Todas as confirmações de uma entrega feita antes da operação de busca falharão. As operações de busca são eventualmente consistentes.
Para mais informações sobre políticas de nova tentativa, consulte Entrega exatamente uma vez.