Depois de acusar a receção de mensagens no Pub/Sub, estas mensagens ficam inacessíveis para o cliente subscritor. Além disso, os clientes subscritores têm de processar todas as mensagens numa subscrição, mesmo que apenas seja necessário um subconjunto.
A funcionalidade procurar expande as capacidades dos subscritores, permitindo-lhe alterar o estado de confirmação das mensagens em massa. Por exemplo, pode repetir mensagens reconhecidas anteriormente ou eliminar mensagens em massa. Além disso, pode copiar o estado de confirmação de uma subscrição para outra usando a funcionalidade de procura em combinação com uma imagem instantânea.
Para uma demonstração rápida de como estas funcionalidades funcionam, consulte o artigo Repita uma mensagem no Pub/Sub procurando um momento específico ou uma data/hora.
Vista geral do instantâneo e da procura
Uma captura instantânea do Pub/Sub é uma vista duradoura, consistente e fiável do estado de confirmação (ack) de mensagens de uma subscrição. Um instantâneo regista o estado de confirmação de todas as mensagens numa subscrição no momento da respetiva criação. Um instantâneo retém as mensagens não reconhecidas da subscrição de origem no momento da criação do instantâneo e quaisquer mensagens publicadas no tópico após a criação do instantâneo.
A duração de um instantâneo é determinada pela lista de pendências existente da subscrição de origem. A duração total é igual a 7 dias menos a idade da mensagem não confirmada mais antiga na subscrição. Por exemplo, considere uma imagem instantânea de uma subscrição com um atraso em que a mensagem não reconhecida mais antiga tem 1 dia. A captura de ecrã expira após 6 dias. Esta cronologia é necessária para que as capturas instantâneas ofereçam uma garantia de entrega forte de, pelo menos, uma vez.
A duração máxima possível de um instantâneo é de sete dias. Não pode criar um instantâneo que expire menos de 1 hora após a hora da sua criação.
A funcionalidade de procura permite-lhe procurar um momento específico ou uma indicação de tempo de uma subscrição. Esta funcionalidade permite-lhe controlar como o Pub/Sub pode enviar mensagens a partir de um ponto específico no tempo ou de uma captura específica.
Para procurar um momento no passado e repetir mensagens reconhecidas anteriormente, tem de configurar primeiro a retenção de mensagens no tópico ou configurar a subscrição para reter mensagens reconhecidas.
Consistência eventual das operações de procura
As operações de procura são estritamente consistentes no que diz respeito à garantia de entrega de mensagens. Isto significa que qualquer mensagem que se torne não reconhecida com base na condição de procura tem a garantia de ser entregue eventualmente após a operação de procura ser bem-sucedida. No entanto, as mensagens entregues não ficam imediatamente consistentes com a operação de procura. Assim, uma mensagem publicada antes da indicação de tempo de procura ou que seja reconhecida num resumo pode ser enviada após a operação de procura. Em certo sentido, a entrega de mensagens funciona como um sistema eventualmente consistente no que diz respeito à operação de procura. A operação pode demorar até um minuto a entrar em vigor.
Exemplos de utilização de operações de procura
- Atualize o código do subscritor em segurança. Uma preocupação com a implementação de novo código de subscrição é que o novo executável pode reconhecer mensagens erroneamente, o que leva à perda de mensagens. A incorporação de instantâneos no processo de implementação permite-lhe recuperar de erros no novo código de subscrição.
- Recupere-se de problemas inesperados com subscritores. Nos casos em que os problemas dos subscritores não estão associados a um evento de implementação específico, pode não ter uma captura de ecrã relevante. Neste caso, se tiver ativado a retenção de mensagens reconhecidas para uma subscrição, procurar um momento no passado dá-lhe uma forma de recuperar do erro.
- Poupe tempo e custos de processamento. Realizar uma confirmação em massa num grande número de mensagens que já não são relevantes.
- Teste o código de subscritor em dados conhecidos. Quando testar o código do subscritor para verificar o desempenho e a consistência, é útil usar os mesmos dados em todas as execuções. As capturas instantâneas permitem dados consistentes com uma semântica forte. Além disso, pode aplicar instantâneos a qualquer subscrição num determinado tópico, incluindo uma subscrição criada recentemente.
Configure a retenção de mensagens
Pode configurar a retenção de mensagens num tópico e configurar qualquer uma das respetivas subscrições para reter mensagens reconhecidas. Pode configurar a retenção de mensagens de tópicos se quiser que as mensagens sejam retidas para repetição durante um período superior ao da retenção de mensagens configurada na subscrição. Nesta situação, o projeto do tópico e o projeto da subscrição são cobrados pelo armazenamento de mensagens de acordo com as respetivas definições de retenção de mensagens.
Se a retenção de mensagens de tópicos não estiver configurada, uma mensagem não acusada é eliminada da subscrição quando a respetiva antiguidade excede a propriedade message_retention_duration da subscrição. Por outro lado, se a retenção de mensagens de tópicos estiver configurada, a mensagem não acusada é eliminada da subscrição apenas quando a respetiva antiguidade excede o máximo de segundos do tópico e da subscrição.message_retention_duration
Configure a retenção de mensagens de tópicos
Por predefinição, um tópico do Pub/Sub rejeita mensagens assim que são
confirmadas por todas as subscrições anexadas ao tópico.
A configuração de um tópico com retenção de mensagens oferece-lhe mais flexibilidade, permitindo que
qualquer subscrição associada ao tópico procure no tempo e reproduza
mensagens reconhecidas anteriormente até ao message_retention_duration do tópico.
A retenção de mensagens de tópicos também permite que uma subscrição reproduza mensagens publicadas antes de criar uma subscrição.
Um tópico pode reter mensagens publicadas durante um máximo de 31 dias (configurável pela propriedade message_retention_duration do tópico), mesmo depois de terem sido reconhecidas por todas as subscrições anexadas. Nos casos em que o valor de
message_retention_duration do tópico é superior ao valor de
message_retention_duration da subscrição, o Pub/Sub rejeita uma mensagem apenas quando
a respetiva antiguidade excede o valor de 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 são faturados ao projeto do tópico.
Consola
Para criar um tópico com a retenção de mensagens ativada, siga estes passos:
Na Google Cloud consola, aceda à página Tópicos do Pub/Sub.
Clique em Criar tópico.
No campo ID do tópico, introduza um ID para o seu tópico.
Ative a opção Definir duração da retenção de mensagens.
Deixe as outras opções nas predefinições.
Use o menu pendente 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 guardar o tópico.
Para atualizar as definições de retenção de mensagens de um tópico:
Selecione o seu tópico na página Tópicos do Pub/Sub.
Clique em Editar 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 selecionando ou desmarcando a opção Ativar retenção de mensagens.
Clique em Atualizar para guardar as alterações ao tópico.
gcloud
Para criar um tópico com uma duração de retenção de mensagens de 7 dias, use o comando gcloud pubsub topics create seguinte:
gcloud pubsub topics create TOPIC_ID --message-retention-duration=7d
Pode atualizar esta definição através de gcloud pubsub topics update
. Isto também lhe permite ativar a retenção de mensagens para um tópico existente:
gcloud pubsub topics update TOPIC_ID --message-retention-duration=1d
Também pode desativar a retenção de mensagens para um tópico com o comando update:
gcloud pubsub topics update TOPIC_ID --clear-message-retention-duration
Configure a retenção de mensagens de subscrição
O Pub/Sub começa a reter mensagens em nome de uma subscrição quando
a subscrição é criada. Por predefinição, o Pub/Sub rejeita uma mensagem de uma subscrição assim que a mensagem é reconhecida.
As mensagens não reconhecidas são retidas durante um período predefinido de 7 dias (configurável pela propriedade message_retention_duration da subscrição).
A configuração de uma subscrição para reter mensagens reconhecidas (através da propriedade
retain_acked_messages) permite repetir mensagens reconhecidas anteriormente retidas pela subscrição. Pode configurar as mensagens para serem retidas durante um máximo de 31 dias numa subscrição. Esta configuração aplica-se a mensagens confirmadas e não confirmadas.
Se uma subscrição estiver configurada para reter mensagens reconhecidas, os custos de armazenamento das mensagens reconhecidas retidas pela subscrição são faturados ao projeto da subscrição.
Consola
Para criar uma subscrição com a retenção de mensagens confirmadas ativada, siga estes passos:
Na Google Cloud consola, aceda à página Subscrições do Pub/Sub.
Clique em Criar subscrição.
No campo ID da subscrição, introduza um ID para a sua subscrição.
Use o menu pendente Duração da retenção de mensagens para selecionar o número de dias, horas e minutos para reter mensagens.
Ative a opção Manter mensagens reconhecidas. Deixe as outras opções nas predefinições.
Clique em Criar subscrição para guardar a subscrição.
Para atualizar as definições de retenção de mensagens de uma subscrição:
Selecione a sua subscrição na página Subscrições do Pub/Sub.
Clique em Editar na parte superior da página de detalhes da subscrição.
Ajuste a duração da retenção de mensagens ou ative ou desative a retenção de mensagens com confirmação de receção selecionando ou desmarcando o campo com a etiqueta Reter mensagens com confirmação de receção.
Clique em Atualizar para guardar as alterações à subscrição.
gcloud
Para criar uma subscrição com a retenção de mensagens confirmadas ativada, use o seguinte comando gcloud pubsub subscriptions create:
gcloud pubsub subscriptions create SUBSCRIPTION_ID --retain-acked-messages --message-retention-duration=5d
Pode atualizar esta definição através de
gcloud pubsub subscriptions update
. Isto também lhe permite ativar a retenção de mensagens com confirmação para uma subscrição existente:
gcloud pubsub subscriptions update SUBSCRIPTION_ID --message-retention-duration=1d
Também pode desativar a retenção de mensagens com ACK para uma subscrição com o comando update:
gcloud pubsub subscriptions update SUBSCRIPTION_ID --no-retain-acked-messages
Criar um instantâneo
Pode criar uma captura de ecrã através da consola, das APIs Google ou da CLI Google Cloud CLI.
Consola
Para criar uma captura instantânea, siga estes passos:
Na Google Cloud consola, aceda à página Instantâneos.
Clique em Criar instantâneo.
Em Selecionar uma subscrição do Pub/Sub, selecione uma subscrição.
Em ID do instantâneo, introduza um nome para o instantâneo.
Para mais informações sobre como atribuir nomes a recursos do Pub/Sub, consulte as diretrizes para atribuir nomes a um tópico, uma subscrição, um esquema ou uma captura de ecrã.
Clique em Criar para criar a captura de ecrã.
Também pode criar um resumo a partir da página Subscrições. Se criar uma captura de ecrã imediatamente após criar uma subscrição, pode receber um erro devido ao atraso de propagação da subscrição recém-criada.
gcloud
Para criar um instantâneo, use o comando gcloud pubsub snapshots create
seguinte:
gcloud pubsub snapshots create \ --project=PROJECT_ID \ --subscription=SUBSCRIPTION_ID \ SNAPSHOT_ID
Substitua o seguinte:
PROJECT_ID. Especifica o ID do projeto.SUBSCRIPTION_ID. Especifica o ID da subscrição.SNAPSHOT_ID. Especifica o ID do resumo.
Procure uma indicação de tempo
A procura de um momento específico marca todas as mensagens recebidas pelo Pub/Sub antes do momento como reconhecidas e todas as mensagens recebidas após o momento como não reconhecidas.
Pode realizar os seguintes tipos de operações de procura com base nas indicações de tempo:
Para eliminar todas as mensagens, pode procurar um momento no futuro.
Para repetir e voltar a processar mensagens reconhecidas anteriormente, procure um momento no passado.
A hora de publicação da mensagem é gerada pelos servidores do Pub/Sub (consulte publishTime na referência da API). Esta abordagem é imprecisa pelos seguintes motivos:
Possível diferença horária entre os servidores do Pub/Sub.
O facto de o Pub/Sub ter de funcionar com a hora de chegada do pedido de publicação, em vez de quando ocorreu um evento no sistema de origem.
Pode procurar um ponto específico no tempo através da consola, das APIs Google ou da CLI do Google Cloud. Antes de procurar uma indicação de tempo numa subscrição, certifique-se de que a retenção de mensagens está ativada na subscrição.
Consola
Para procurar uma indicação de tempo, siga estes passos:
Na Google Cloud consola, aceda à página Subscrição.
Clique numa subscrição que tenha a retenção de mensagens ativada.
Na página de detalhes da subscrição, clique em Repetir mensagens.
Para Procurar, clique em Para um ponto temporal anterior.
Selecione uma data e uma hora adequadas e, de seguida, clique em Procurar.
gcloud
Para procurar um ponto específico no tempo, use o seguinte comando: gcloud pubsub subscriptions seek
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \ --time=TIME \
Substitua o seguinte:
- TIME: o tempo para o qual quer realizar a operação de procura.
- SUBSCRIPTION_ID: o ID da subscrição.
Para mais informações sobre os formatos de hora suportados, consulte o artigo gcloud topic datetimes.
Procure um instantâneo
Pode repetir mensagens não reconhecidas usando uma captura instantânea para procurar qualquer uma das subscrições do tópico.
Ao contrário do que acontece quando procura um momento específico, não precisa de fazer nenhuma configuração especial de subscrição para procurar um resumo. Só tem de criar a imagem instantânea antecipadamente. Por exemplo, pode criar uma captura de ecrã quando implementar um novo código de subscritor, caso precise de recuperar de reconhecimentos inesperados ou erróneos.
Se o registo pendente na subscrição for demasiado antigo e a imagem instantânea resultante expirar em menos de 1 hora, a operação de procura falha.
Pode procurar um instantâneo através da consola, das APIs Google ou da CLI do Google Cloud.
Consola
Para procurar uma imagem instantânea, siga estes passos:
Na Google Cloud consola, aceda à página Subscrição.
Clique numa subscrição.
Na página de detalhes da subscrição, clique em Repetir mensagens.
Para Procurar, clique em Para um resumo.
Selecione uma imagem instantânea adequada e, de seguida, clique em Procurar.
gcloud
Para procurar um momento específico, use o comando
seguinte
gcloud pubsub subscriptions seek:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \ --snapshot=SNAPSHOT_ID
Substitua o seguinte:
- SNAPSHOT_ID: o ID de um resumo. O tópico da imagem instantânea tem de ser o mesmo que o da subscrição.
- SUBSCRIPTION_ID: o ID da subscrição.
Procure com filtros
Pode repetir mensagens de subscrições com filtros. Se procurar uma data/hora através de uma subscrição com um filtro, o serviço Pub/Sub só volta a enviar as mensagens que correspondem ao filtro.
Uma captura de ecrã de uma subscrição com um filtro contém as seguintes mensagens:
- Todas as mensagens mais recentes do que a captura instantânea, incluindo as mensagens que não correspondem ao filtro.
- Mensagens não reconhecidas mais antigas do que a imagem instantânea.
Se procurar um instantâneo através de uma subscrição com um filtro, o serviço Pub/Sub apenas volta a enviar as mensagens no instantâneo que correspondem ao filtro da subscrição que está a fazer o pedido de procura.
Para mais informações sobre filtros, consulte o artigo Filtrar mensagens.
Procure com tópicos de mensagens não entregues
Se procurar mensagens numa subscrição com um tópico de mensagens não entregues, o Pub/Sub define as tentativas de entrega como 0. As mensagens que recebe destas subscrições têm um campo que contabiliza o número de tentativas de entrega.
Para mais informações sobre tópicos de mensagens não entregues, consulte o artigo Encaminhamento para tópicos de mensagens não entregues.
Procure com políticas de repetição
Se procurar mensagens numa subscrição com uma política de repetição, o Pub/Sub repõe o atraso entre o seguinte:
- O prazo de confirmação expirar ou o subscritor enviar uma confirmação negativa.
- O Pub/Sub reenvia a mensagem.
Para mais informações sobre as políticas de repetição, consulte o artigo Usar políticas de repetição.
Procure com entrega exatamente uma vez
Se procurar mensagens numa subscrição com entrega exatamente uma vez, o Pub/Sub reenvia as mensagens reconhecidas anteriormente que são elegíveis para entrega. Todas as confirmações de uma entrega feita antes da operação seek falham. As operações de procura são eventualmente consistentes.
Para mais informações sobre as políticas de repetição, consulte o artigo Entrega exatamente uma vez.