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:
No console, acesse a página 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.
Marque a caixa ao lado de Definir a duração da retenção de mensagens. Não altere as outras opções.
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.
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 caixa 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
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:
No console, acesse a página Assinaturas do Pub/Sub.
Clique em Criar assinatura.
No campo ID da assinatura, insira um ID para a assinatura.
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.
Marque a caixa de seleçã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 visualizadas marcando ou desmarcando a caixa 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=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:
- 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 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.