Os assinantes podem não conseguir processar mensagens por vários motivos. Por exemplo, pode haver problemas transitórios na recuperação dos dados necessários para processar uma mensagem. Ou a mensagem pode estar em um formato não esperado pelo assinante.
Esta página explica 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 tenta entregar uma mensagem, mas o assinante não consegue confirmá-la, o Pub/Sub automaticamente tenta reenviar a mensagem. Essa tentativa de reenvio é conhecida como política de nova tentativa de assinatura. Esse não é um recurso que pode ser ativado ou desativado, mas é possível escolher o tipo de política de novas tentativas 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 espera exponencial. Por padrão, as assinaturas usam a reenvio imediata.
Reenviar 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 tiverem mudado, o reenvio imediato pode causar problemas. Nesse caso, é possível que o Pub/Sub reenvie várias mensagens que não foram confirmadas.
Para resolver problemas de reenvio imediatos, é possível configurar uma política de espera exponencial no Pub/Sub.
Espera exponencial
A espera exponencial permite adicionar atrasos progressivamente mais entre tentativas de novas tentativas. Após a primeira falha na entrega, o Pub/Sub aguarda um tempo mínimo de espera antes de tentar novamente. Para cada falha consecutiva de mensagem, é adicionado mais tempo ao atraso, até um atraso máximo (0 a 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 só é aplicada por mensagem, e não a todas as mensagens em uma assinatura (global).
- Durante o uso da espera exponencial, o Pub/Sub continua a entregar outras mensagens, mesmo que elas tenham recebido confirmações negativas (a menos que você esteja usando a entrega de mensagens ordenada).
Configurar a 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 como dar um nome a 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 envio.
Em Política de nova tentativa, selecione Repetir após espera exponencial.
Defina 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, 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 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 de entrega máximas são calculadas
O Pub/Sub só conta as tentativas de entrega quando um tópico de mensagens inativas é 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, primeiro o tópico de origem precisa ter uma assinatura. É possível especificar um tópico de mensagens inativas ao criar a assinatura ou atualizar uma assinatura existente para que tenha um tópico de mensagens inativas.
Confira a seguir o fluxo de trabalho para ativar mensagens inativas em uma assinatura.
Crie o tópico de mensagens inativas. Este tema é separado do tema de origem.
Define 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 a ele. A assinatura secundária recebe mensagens do tópico de mensagens inativas.
Conceda os papéis de editor e de 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 ações necessárias possíveis. 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 de 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 Ruby do Pub/Sub.
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
É 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 ações necessárias possíveis. 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 de 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 Ruby do Pub/Sub.
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, 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
.
É possível conceder permissões de encaminhamento atribuindo papéis de editor e de assinante a essa conta de serviço.
Console
Para conceder permissão ao Pub/Sub 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 Letras inativas.
Para atribuir um papel 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 um papel de assinante, clique em Conceder papel 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ê ativa um tópico de mensagens inativas para uma assinatura, cada mensagem dessa assinatura tem um campo que especifica o número de tentativas de entrega:
As mensagens recebidas de uma assinatura de envio 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 de 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 C# do Pub/Sub.
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 de 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 Go do Pub/Sub.
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 de 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 Java do Pub/Sub.
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 de 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 Node.js do Pub/Sub.
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 de 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 PHP do Pub/Sub.
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 de 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 Python do Pub/Sub.
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 de 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 Ruby do Pub/Sub.
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 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 só existe para assinaturas de exportação.
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 de 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 Ruby do Pub/Sub.
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.