Após a confirmação das mensagens no Pub/Sub, elas ficam inacessíveis ao cliente do 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 seek 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. Além disso, é possível copiar o estado de confirmação de uma assinatura para 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 visão pontual, consistente e confiável do estado de confirmação de mensagens (ack) de uma assinatura. Um snapshot registra o estado de confirmação de todas as mensagens em uma assinatura no momento da criação dela. Um snapshot retém as mensagens não confirmadas da assinatura de origem no momento da criação do snapshot, bem como 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. O ciclo de vida é igual a sete dias menos a idade da mensagem não confirmada mais antiga na assinatura. Por exemplo, pense em 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 seis dias. Esse cronograma é necessário para que os snapshots ofereçam uma forte 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 uma hora após a criação.
O recurso de busca permite buscar um snapshot ou carimbo de data/hora específico de uma assinatura. Esse recurso permite controlar como o Pub/Sub pode entregar mensagens de um momento específico 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.
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 tem 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 certa forma, a entrega de mensagens opera como um sistema de consistência posterior 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.
Configurar a retenção de mensagens
É possível configurar a retenção de mensagens em um tópico e configurar qualquer uma das assinaturas dele para reter mensagens confirmadas. Configure a retenção de mensagens de tópico se quiser que elas sejam retidas para repetição por um período maior do que a retenção de mensagens configurada na assinatura. Nessa situação, o projeto do tópico e o da assinatura são cobrados pelo armazenamento de mensagens de acordo com as respectivas configurações de retenção de mensagens.
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.
Configurar a retenção de mensagens de tópicos
Por padrão, um tópico do Pub/Sub descarta mensagens assim que são
confirmadas por todas as assinaturas anexadas a ele.
A configuração de um tópico com a retenção de mensagens oferece mais flexibilidade, permitindo
que qualquer assinatura anexada ao tópico volte no tempo e repita
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 do tópico estiver ativada, os custos de armazenamento das mensagens retidas pelo tópico serão faturados para o projeto do tópico.
Console
Para criar um tópico com a retenção de mensagens ativada, siga estas etapas:
No console do Google Cloud, acesse a página de tópicos do Pub/Sub.
Clique em Criar tópico.
No campo Código do tópico, insira um código para o tópico.
Ative Definir duração da retenção de mensagens.
Não altere as outras opções.
Use o menu suspenso Duração da retenção de mensagens para selecionar o número de dias, horas e minutos em que as mensagens serão retidas.
Clique em Criar tópico para salvar o tópico.
Para atualizar as configurações de retenção de mensagens de um tópico:
Selecione o tópico na página Tópicos do Pub/Sub.
Clique em Editar também na parte superior da página de detalhes do tópico.
Ajuste o tempo de retenção ou ative ou desative a retenção de mensagens marcando ou desmarcando a opção Ativar retenção de mensagens.
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
Configurar a retenção de mensagens da assinatura
O Pub/Sub começa a reter mensagens em nome de uma assinatura quando
ela é criada. Por padrão, o Pub/Sub descarta uma
mensagem de uma assinatura assim que ela é confirmada.
As mensagens não confirmadas são retidas por um padrão de sete dias, o que pode ser configurado pela
propriedade message_retention_duration
da assinatura.
A configuração de uma assinatura para reter mensagens confirmadas (usando a propriedade
retain_acked_messages)
permite reproduzir mensagens confirmadas anteriormente
retidas pela assinatura. Você pode configurar a retenção de mensagens por um
máximo de sete dias em uma assinatura. Essa configuração se aplica a mensagens confirmadas e não confirmadas. No entanto, as mensagens poderão ser retidas em uma
assinatura por mais de sete dias se a duração da retenção da mensagem configurada
no tópico for maior que esse período.
Se uma assinatura estiver configurada para reter mensagens confirmadas, os custos de armazenamento das mensagens confirmadas retidas pela assinatura serão cobrados no projeto da assinatura.
Console
Para criar uma assinatura com a retenção de mensagens visualizadas ativadas, siga estas etapas:
No console do Google Cloud, acesse a página Assinaturas do Pub/Sub.
Clique em Criar assinatura.
No campo ID da assinatura, insira um ID para a assinatura.
Use o menu suspenso Duração da retenção de mensagens para selecionar o número de dias, horas e minutos de retenção das mensagens.
Ative Reter mensagens confirmadas. Não altere as outras opções.
Clique em Criar assinatura para salvá-la.
Para atualizar as configurações de retenção de mensagens de uma assinatura:
Selecione sua assinatura na página de Assinaturas do Pub/Sub.
Clique em Editar também na parte superior da página de detalhes da assinatura.
Ajuste a duração da retenção de mensagens ou ative ou desative a retenção de mensagens confirmadas marcando ou desmarcando o campo Reter mensagens confirmadas.
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
--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 confirmadas 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 --no-retain-acked-messages
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 console do Google Cloud, acesse a página Snapshots.
Clique em Criar snapshot.
Em Selecionar uma assinatura do Pub/Sub, escolha uma assinatura.
Em Código do snapshot, insira um nome para ele.
Para mais informações sobre como nomear recursos do Pub/Sub, consulte Diretrizes para nomear um tópico, uma assinatura, um esquema ou um snapshot.
Clique em Criar para criar o snapshot.
Também é possível criar um snapshot na página Assinaturas.
gcloud
Para criar um snapshot, use o
seguinte
comando
gcloud pubsub snapshots create:
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 executar os seguintes tipos de operações de busca com base em carimbos de data/hora:
Para limpar todas as mensagens, você pode procurar um horário no futuro.
Para reproduzir e reprocessar mensagens confirmadas anteriormente, busque 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.
Procure um carimbo de data/hora usando o console, as APIs do Google ou a CLI do Google Cloud. Antes de procurar 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 console do Google Cloud, acesse a página Assinatura.
Clique em uma assinatura com a retenção de mensagens ativada.
Na página de detalhes da assinatura, clique em Repetir mensagens.
Em Procurar, clique em Para um ponto anterior.
Selecione uma data e hora apropriadas e clique em Procurar.
gcloud
Para buscar um carimbo de data/hora, use o
seguinte
comando gcloud pubsub subscriptions seek:
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 os formatos de hora compatíveis, consulte gcloud topic datetimes.
Procurar 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 uma 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 console do Google Cloud, acesse a página Assinatura.
Clique em uma assinatura.
Na página de detalhes da assinatura, clique em Repetir mensagens.
Em Busca, clique em Para um snapshot.
Selecione um snapshot apropriado e clique em Buscar.
gcloud
Para buscar um snapshot, use o
seguinte
comando
gcloud pubsub subscriptions seek:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \
--snapshot=SNAPSHOT_ID
Substitua:
- SNAPSHOT_ID: o ID de um snapshot. O tópico do snapshot precisa ser igual ao da assinatura.
- SUBSCRIPTION_ID: o ID da assinatura.
Procurar 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.
Procure com temas de 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 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.
Procure com exatamente uma entrega
Se você busca mensagens em uma assinatura com entrega exatamente uma vez, o Pub/Sub reenvia as mensagens confirmadas anteriormente que estã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 têm consistência posterior.
Para mais informações sobre políticas de novas tentativas, consulte Entrega exatamente uma vez.