Os inscritos podem não conseguir lidar com as mensagens por vários motivos. Por exemplo, pode haver problemas transitórios ao recuperar os dados necessários para processar uma mensagem. Ou uma mensagem pode estar em um formato que o assinante não espera.
Nesta página, explicamos como lidar com essas falhas de processamento usando uma política de repetição de assinatura ou encaminhando mensagens não entregues para um tópico de mensagens inativas, também conhecido como fila de mensagens inativas.
Esses recursos não são compatíveis com o Dataflow. Consulte a seção Recursos sem suporte do Pub/Sub na documentação do Dataflow para ver mais informações.
Política de repetição de assinatura
Se o Pub/Sub tentar entregar uma mensagem, mas o assinante não puder confirmá-la, o Pub/Sub tentará reenviar a mensagem automaticamente. Essa tentativa de reenvio é conhecida como a política de nova tentativa de assinatura. Esse não é um recurso que você pode ativar ou desativar. No entanto, é possível escolher o tipo de política de repetição que você quer usar.
Ao criar e configurar sua assinatura pela primeira vez, você pode optar por usar uma das seguintes políticas de nova tentativa, reenvio imediato ou retirada exponencial. Por padrão, as assinaturas usam um reenvio imediato.
Reenvio imediato
Por padrão, o Pub/Sub tenta reenviar a mensagem imediatamente (e potencialmente para o mesmo cliente assinante). No entanto, se as condições que impediram a confirmação da mensagem não foram alteradas, o reenvio imediato pode causar problemas. Nesse caso, é possível que o Pub/Sub reenvie várias mensagens que não podem ser confirmadas.
Para resolver problemas de reenvio imediato, o Pub/Sub permite configurar uma política de espera exponencial.
Espera exponencial
A espera exponencial permite adicionar atrasos progressivamente mais longos entre as tentativas de repetição. Após a primeira falha na entrega, o Pub/Sub espera um tempo mínimo de espera antes de tentar novamente. Para cada falha de mensagem consecutivas, mais tempo é adicionado ao atraso, até um atraso máximo (0 e 600 segundos).
Os intervalos de atraso máximo e mínimo não são fixos e precisam ser configurados com base em fatores locais do aplicativo.
Observe as seguintes considerações sobre espera exponencial:
- Acionadores de espera exponencial nas seguintes ações:
- Quando uma confirmação negativa é recebida.
- Quando o prazo de confirmação de uma mensagem expira.
- A espera exponencial só é aplicada por mensagem, e não a todas as mensagens em uma assinatura (global).
- Enquanto você estiver usando a espera exponencial, o Pub/Sub continuará entregando outras mensagens, mesmo que as mensagens anteriores recebam confirmações negativas (a menos que você esteja usando a entrega ordenada de mensagens).
Configurar espera exponencial
Console
Ao criar uma nova assinatura, siga as etapas a seguir para configurar uma política de repetição com espera exponencial:
No Console do Google Cloud, acesse a página Assinaturas do Pub/Sub.
Clique em Criar assinatura.
No campo ID da assinatura, digite um nome.
Para informações sobre como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
Escolha ou crie um tópico no menu suspenso.
A assinatura recebe mensagens do tópico.
Selecione um Tipo de entrega.
Em Política de repetição, selecione Tentar novamente após a espera exponencial.
Insira uma Espera mínima e uma Espera máxima entre 0 e 600 segundos.
Os valores padrão são 10 segundos na espera mínima e 600 na máxima.
Clique em Criar.
gcloud
Para criar uma nova assinatura com uma política de repetição com espera exponencial, execute o comando gcloud pubsub create
com as sinalizações mostradas abaixo:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --min-retry-delay=MIN_RETRY_DELAY \ --max-retry-delay=MAX_RETRY_DELAY
Tópico de mensagens inativas
Se o serviço do Pub/Sub tentar entregar uma mensagem, mas o assinante não a reconhecer, o Pub/Sub poderá encaminhar a mensagem não entregue para um tópico de mensagens inativas.
Como os tópicos de mensagens inativas funcionam com o Pub/Sub
Um tópico de mensagens inativas é uma propriedade de assinatura, não uma propriedade de tópico. Isso significa que você define um tópico de mensagens inativas ao criar uma assinatura, e não ao criar um tópico.
Se você criar um tópico de mensagens inativas, poderá definir as seguintes propriedades de assinatura:
Número máximo de tentativas de entrega: um valor numérico que representa o número de tentativas de entrega que o Pub/Sub faz para uma mensagem específica. Se o cliente do assinante não puder confirmar a mensagem no número configurado de tentativas de entrega, a mensagem será encaminhada para um tópico de mensagens inativas.
- Valor padrão = 5
- Valor máximo = 100
- Valor mínimo = 5
Projeto com tópico de mensagens inativas: se o tópico de mensagens inativas estiver em um projeto diferente da assinatura, será preciso especificar esse projeto. Defina o tópico de mensagens inativas como um tópico diferente daquele em que a assinatura está anexada.
Como são calculadas as tentativas de entrega máxima
O Pub/Sub só conta as tentativas de entrega quando um tópico de mensagens inativas está configurado corretamente e inclui as permissões do IAM corretas.
O número máximo de tentativas de entrega é aproximado porque o Pub/Sub encaminha mensagens que não podem ser entregues com base no melhor esforço.
O número rastreado de tentativas de entrega de uma mensagem também pode ser redefinido como zero, especialmente para uma assinatura de pull com assinantes inativos. Como resultado, as mensagens podem ser entregues ao cliente assinante mais vezes do que o número máximo configurado de tentativas de entrega.
Configurar um tópico de mensagens inativas
Para configurar um tópico de mensagens inativas, o tópico de origem precisa ter uma assinatura primeiro. Você pode especificar um tópico de mensagens inativas ao criar a assinatura ou atualizar uma assinatura existente para ter um tópico de mensagens inativas.
Veja a seguir o fluxo de trabalho para ativar mensagens inativas em uma assinatura.
Crie o tópico de mensagens inativas. Este tópico é separado do tópico de origem.
Defina o tópico de mensagens inativas na assinatura do tópico de origem.
Para evitar a perda de mensagens do tópico de mensagens inativas, anexe pelo menos uma outra assinatura ao tópico de mensagens inativas. A assinatura secundária recebe mensagens do tópico de mensagens inativas.
Conceda os papéis de editor e assinante à conta de serviço do Pub/Sub. Para mais informações, consulte Conceder permissões de encaminhamento.
Definir um tópico de mensagens inativas em uma nova assinatura
É possível criar uma assinatura e definir um tópico de mensagens inativas usando o console do Google Cloud, a Google Cloud CLI, as bibliotecas de cliente ou a API Pub/Sub.
Console
Para criar uma assinatura e definir um tópico de mensagens inativas, siga as etapas a seguir:
No Console do Google Cloud, acesse a página Assinaturas.
Clique em Criar assinatura.
Insira o ID da assinatura.
Escolha ou crie um tópico no menu suspenso.
A assinatura recebe mensagens do tópico.
Na seção Mensagens mortas, selecione Ativar mensagens mortas.
Escolha ou crie um tópico de mensagens inativas no menu suspenso.
Se o tópico de mensagens inativas escolhido não tiver uma assinatura, o sistema solicitará que você crie uma.
No campo Máximo de tentativas de entrega, especifique um número inteiro entre 5 e 100.
Clique em Criar.
O painel de detalhes mostra uma lista de possíveis ações necessárias. Se algum dos itens mostrar um ícone de erro
, clique no item de ação para resolver o problema.
gcloud
Para criar uma assinatura e definir um tópico de mensagens inativas, use o comando gcloud pubsub subscriptions create
:
gcloud pubsub subscriptions create subscription-id \ --topic=topic-id \ --dead-letter-topic=dead-letter-topic-name \ [--max-delivery-attempts=max-delivery-attempts] \ [--dead-letter-topic-project=dead-letter-topic-project]
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Definir um tópico de mensagens inativas para uma assinatura existente
É possível atualizar uma assinatura e definir um tópico de mensagens inativas usando o console do Google Cloud, a Google Cloud CLI, as bibliotecas de cliente ou a API Pub/Sub.
Console
Para atualizar uma assinatura e definir um tópico de mensagens inativas, siga as etapas a seguir.
No Console do Google Cloud, acesse a página Assinaturas.
Ao lado da assinatura a ser atualizada, clique em Mais açõesmore_vert.
No menu de contexto, selecione Editar.
Na seção Mensagens mortas, selecione Ativar mensagens mortas.
Escolha ou crie um tópico no menu suspenso.
Se o tópico escolhido não tiver uma assinatura, o sistema solicitará a criação de uma.
No campo Máximo de tentativas de entrega, especifique um número inteiro entre 5 e 100.
Clique em Atualizar.
O painel de detalhes mostra uma lista de possíveis ações necessárias. Se algum dos itens mostrar um ícone de erro
, clique no item de ação para resolver o problema.
gcloud
Para atualizar uma assinatura e definir um tópico de mensagens inativas, use o comando gcloud pubsub subscriptions update
:
gcloud pubsub subscriptions update subscription-id \ --dead-letter-topic=dead-letter-topic-name \ [--max-delivery-attempts=max-delivery-attempts] \ [--dead-letter-topic-project=dead-letter-topic-project]
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Conceder papéis do IAM para usar tópicos de mensagens inativas
Para encaminhar mensagens não entregues a um tópico de mensagens inativas, o Pub/Sub precisa de permissão para fazer o seguinte:
- Publicar mensagens no tópico.
- Confirme as mensagens, que as removem da assinatura.
O Pub/Sub cria e mantém uma conta de serviço para cada
projeto:
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
.
Para conceder permissões de encaminhamento, atribua papéis de editor e assinante a essa conta de serviço.
Console
Para conceder ao Pub/Sub permissão para publicar mensagens em um tópico de mensagens inativas, siga estas etapas:
No Console do Google Cloud, acesse a página Assinaturas.
Clique no nome da assinatura que tem o tópico de mensagens inativas.
Clique na guia Mensagens mortas.
Para atribuir uma função de editor, clique em Conceder papel de editor. Se o papel de editor for atribuído, você verá uma marca de seleção azul
.Para atribuir uma função de assinante, clique em Conceder função de assinante. Se o papel de editor for atribuído, você verá uma marca de seleção azul
.
gcloud
Para conceder permissão para que o Pub/Sub publique mensagens no tópico de mensagens inativas, execute o comando a seguir:
PUBSUB_SERVICE_ACCOUNT="service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com" gcloud pubsub topics add-iam-policy-binding dead-letter-topic-name \ --member="serviceAccount:$PUBSUB_SERVICE_ACCOUNT"\ --role="roles/pubsub.publisher"
Para conceder ao Pub/Sub permissão para confirmar as mensagens não entregues encaminhadas, execute o comando a seguir:
PUBSUB_SERVICE_ACCOUNT="service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com" gcloud pubsub subscriptions add-iam-policy-binding subscription-id \ --member="serviceAccount:$PUBSUB_SERVICE_ACCOUNT"\ --role="roles/pubsub.subscriber"
Rastrear tentativas de entrega
Depois que você ativar um tópico de mensagens inativas para uma assinatura, cada mensagem dessa assinatura terá um campo que especifica o número de tentativas de entrega:
As mensagens recebidas de uma assinatura de pull incluem o campo
delivery_attempt
.As mensagens recebidas de uma assinatura de push incluem o campo
deliveryAttempt
.
Os exemplos a seguir mostram como ver o número de tentativas de entrega:
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Quando o Pub/Sub encaminha uma mensagem que não foi entregue a um tópico de mensagens inativas, os seguintes atributos são adicionados a ela:
CloudPubSubDeadLetterSourceDeliveryCount
: o número de tentativas de entrega da assinatura de origem.CloudPubSubDeadLetterSourceSubscription
: o nome da assinatura de origem.CloudPubSubDeadLetterSourceSubscriptionProject
: o nome do projeto que contém a assinatura de origem.CloudPubSubDeadLetterSourceTopicPublishTime
: o carimbo de data/hora em que a mensagem foi publicada originalmente.
Monitorar mensagens encaminhadas
Depois de encaminhar uma mensagem não entregue, o serviço do Pub/Sub a remove da assinatura. É possível monitorar mensagens encaminhadas com o Cloud Monitoring.
Se você anexar uma assinatura ao tópico de mensagens inativas, as mensagens usarão a política de expiração da assinatura anexada, em vez do período de validade da assinatura com a propriedade de tópico de mensagens inativas.
A métrica subscription/dead_letter_message_count
registra o número de mensagens não entregues que o Pub/Sub encaminha de uma assinatura.
Para ver mais informações, consulte Como monitorar mensagens não entregues encaminhadas.
Remover um tópico de mensagens inativas
Para interromper o encaminhamento de mensagens não entregues, remova o tópico de mensagens inativas da assinatura.
É possível remover um tópico de mensagens inativas de uma assinatura usando o console do Google Cloud, a Google Cloud CLI ou a API Pub/Sub.
Console
Para remover um tópico de mensagens inativas de uma assinatura, siga as etapas a seguir:
No Console do Google Cloud, acesse a página Assinaturas.
Na lista de assinaturas, clique em more_vert ao lado da assinatura para atualizar.
No menu de contexto, selecione Editar.
Na seção Mensagens mortas, desmarque Ativar mensagens mortas.
Clique em Update.
gcloud
Para remover um tópico de mensagens inativas de uma assinatura, use o comando gcloud pubsub subscriptions update
e a sinalização --clear-dead-letter-policy
:
gcloud pubsub subscriptions update subscription-id \ --clear-dead-letter-policy
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Preços
Quando o serviço do Pub/Sub encaminha mensagens não entregues, são aplicadas as taxas a seguir:
- Taxas de publicação cobradas à conta de faturamento associada ao projeto que contém o tópico de mensagens inativas.
- Taxas de saída da assinatura cobradas à conta de faturamento associada ao projeto que contém a assinatura com a propriedade do tópico de mensagens inativas.
Se você definir a propriedade do tópico de mensagens inativas em uma assinatura, mas sua política de local de armazenamento de mensagens não permite a região que contém a assinatura, também serão aplicadas taxas de saída.
As taxas de saída de publicação são cobradas ao projeto que contém o tópico de mensagens inativas. Para mais informações, consulte Preços.
A seguir
- Receba as mensagens não entregues encaminhadas.
- Monitore os aplicativos Pub/Sub.
- Conheça os conceitos de entrega de mensagens.