Os assinantes podem não conseguir processar mensagens por vários motivos. Por exemplo, pode haver problemas temporários ao recuperar 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 nova tentativa 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 nova tentativa de assinatura
Se o Pub/Sub tentar entregar uma mensagem, mas o assinante não reconhecê-la, o Pub/Sub tentará reenviá-la automaticamente. Essa tentativa de reenvio é conhecida como política de nova tentativa de assinatura. Esse não é um recurso que você pode ativar ou desativar, mas pode escolher o tipo de política de nova tentativa que 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 espera exponencial. Por padrão, as assinaturas usam o reenvio imediato.
Reenvio imediato
Por padrão, o Pub/Sub tenta reenviar a mensagem imediatamente (e possivelmente para o mesmo cliente assinante). No entanto, se as condições que impediam 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 possam ser confirmadas.
Para resolver problemas de reenvio imediatos, o Pub/Sub permite configurar uma política de espera exponencial.
Espera exponencial
A espera exponencial permite adicionar atrasos progressivamente maiores entre as tentativas de repetição. Após a primeira falha na entrega, o Pub/Sub aguarda um tempo mínimo de espera antes de tentar novamente. Para cada falha de mensagem consecutiva, é adicionado mais tempo ao atraso até um 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 a espera exponencial:
- A espera exponencial é acionada nas seguintes ações:
- Quando uma confirmação negativa é recebida.
- Quando o prazo de confirmação de uma mensagem expira.
- A espera exponencial é aplicada apenas por mensagem, e não a todas as mensagens em uma assinatura (global).
- Enquanto estiver usando a espera exponencial, o Pub/Sub continuará a entregar outras mensagens, mesmo que as mensagens anteriores tenham recebido 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 saber mais 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 Pub/Sub tentar entregar uma mensagem, mas o assinante não conseguir reconhecê-la, 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, não ao criar um tópico.
Se você criar um tópico de mensagens inativas, será possível definir as seguintes propriedades de assinatura:
Número máximo de tentativas de entrega: um valor numérico que indica 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 dentro do 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 a que a assinatura está anexada.
Como as tentativas máximas de entrega são calculadas
O Pub/Sub conta as tentativas de entrega somente 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 as mensagens não 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. É possível especificar um tópico de mensagens inativas ao criar a assinatura ou atualizar uma assinatura atual para que ela tenha 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.
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: como usar 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 atual
É 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á que você crie 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: como usar 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 de 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.
- Confirmar as mensagens, o que as remove 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
.
Atribua permissões de encaminhamento atribuindo
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, conclua as seguintes 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 função 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 de 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: como usar 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: como usar 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: como usar 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: como usar 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: como usar 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: como usar 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: como usar 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 é entregue para um tópico de mensagens inativas, ele adiciona os seguintes atributos à mensagem:
CloudPubSubDeadLetterSourceDeliveryCount
: o número de tentativas de entrega para a 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.CloudPubSubDeadLetterSourceDeliveryErrorMessage
: o motivo pelo qual a mensagem não foi entregue ao destino original. O atributo existe apenas para exportar assinaturas.
Monitorar mensagens encaminhadas
Depois de encaminhar uma mensagem não entregue, o serviço do Pub/Sub a remove da assinatura. É possível monitorar as 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: como usar 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 assinatura para mensagens de saída faturadas na conta de faturamento associada ao projeto que contém a assinatura com a propriedade tópico de mensagens inativas.
Se você definir a propriedade de tópico de mensagens inativas de uma assinatura, mas a política de local de armazenamento de mensagens do tópico de mensagens inativas não permitir a região que contém a assinatura, as taxas de publicação para mensagens de saída também serão aplicadas.
As taxas de publicação para mensagens de saída são cobradas do 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.