Depois que você confirma as mensagens no Pub/Sub, elas ficam inacessíveis para o 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 Busca amplia os recursos do assinante, permitindo alterar 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 Reproduzir 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 (ACK) 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 de idade. O snapshot expira após seis 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 uma hora após a criação.
O recurso de busca permite buscar um snapshot ou carimbo de data/hora específico para uma assinatura. Esse recurso permite controlar como o Pub/Sub pode enviar 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.
Consistência eventual 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 certo modo, a entrega de mensagens funciona como um sistema consistente com 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 para reter mensagens confirmadas. Convém configurar a retenção de mensagens do tópico se quiser que as mensagens sejam retidas para reproduçã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 projeto 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ó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
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ópicos 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:
No console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Clique em Criar tópico.
No campo ID do tópico, insira um ID para o tópico.
Ative a opção Definir a 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 para reter mensagens.
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/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 de 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.
Mensagens não confirmadas são retidas por padrão por sete dias (configurável pela
propriedade message_retention_duration
da assinatura).
Configurar uma assinatura para reter mensagens confirmadas (usando a
propriedade retain_acked_messages)
permite reproduzir mensagens recebidas anteriormente
retidas pela assinatura. É possível configurar as mensagens para serem retidas por no máximo 31 dias em uma assinatura. Essa
configuração se aplica a mensagens confirmadas e não confirmadas.
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:
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 para reter mensagens.
Ative a opção 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 da mensagem ou ative/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 visualizadas 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 ID do snapshot, insira um nome para o snapshot.
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. 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
comando
gcloud pubsub snapshots create
abaixo:
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 repetir 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 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 Assinaturas.
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 no tempo.
Selecione uma data e hora adequadas e clique em Procurar.
gcloud
Para buscar um carimbo de data/hora, use o
comando
gcloud pubsub subscriptions seek
a seguir:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \ --time=TIME \
Substitua:
- TIME: o tempo em que você quer realizar a operação de busca.
- SUBSCRIPTION_ID: o ID da assinatura.
Para mais informações sobre os formatos de tempo aceitos, consulte Data e hora no gcloud.
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 Instant 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 Assinaturas.
Clique em uma assinatura.
Na página de detalhes da assinatura, clique em Repetir mensagens.
Em Procurar, clique em Para um snapshot.
Selecione um snapshot adequado e clique em Procurar.
gcloud
Para buscar um snapshot, use o
comando
gcloud pubsub subscriptions seek
a seguir:
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.
Procurar com tópicos 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.
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.
Busca com entrega exatamente uma vez
Se você buscar mensagens em uma assinatura com entrega exatamente uma vez, o Pub/Sub vai reenviar as mensagens confirmadas anteriormente que estão qualificadas para entrega. Qualquer confirmação de uma entrega feita antes da operação de busca vai falhar. As operações de busca têm consistência posterior.
Para mais informações sobre políticas de nova tentativa, consulte Envio exatamente uma vez.