Nesta página, explicamos como receber e confirmar mensagens usando semântica exatamente uma. Somente o tipo de assinatura de pull é compatível com entrega exatamente uma vez, incluindo assinantes que usam a API StreamingPull.
As assinaturas de push e exportação não são compatíveis com o envio único.
Versões recomendadas da biblioteca de cliente
- Para um melhor desempenho, use a versão mais recente da biblioteca de cliente, Python v2.13.6 ou mais recente, Java v1.120.11 ou mais recente, PHP v1.39.0 ou mais recente, C# v3.2.0 ou posterior, C++ v2.1.0, Go {21.v1.1ou mais recente.
Entrega exatamente uma vez
O Pub/Sub é compatível com entrega única, em uma região da nuvem, com base em um ID de mensagem exclusivo definido pelo Pub/Sub.
Quando o recurso está ativado, o Pub/Sub fornece o seguinte:
Nenhum reenvio ocorre após a confirmação da mensagem.
Não ocorre reenvio enquanto uma mensagem está pendente. Uma mensagem é considerada pendente até que o prazo de confirmação expire ou ela seja confirmada.
No caso de várias entregas válidas, devido à expiração do prazo de confirmação ou à confirmação negativa iniciada pelo cliente, apenas o ID de confirmação mais recente pode ser usado para confirmar a mensagem. Todas as solicitações com um ID de confirmação anterior falham.
Reenvio versus duplicado
É importante entender a diferença entre reenvios esperados e inesperados.
Um reenvio pode ocorrer devido à confirmação negativa iniciada pelo cliente de uma mensagem ou quando o cliente não estende o prazo de confirmação da mensagem antes que o prazo expire. As reenvios são consideradas válidas e o sistema está funcionando conforme o esperado.
Para resolver problemas de reenvios, consulte Como lidar com cópias e forçar novas tentativas.
Uma cópia é quando uma mensagem é reenviada após uma confirmação bem-sucedida ou antes da expiração do prazo de confirmação.
Uma mensagem reenviada mantém o mesmo ID entre as tentativas de reenvio.
As assinaturas com o envio único ativado não recebem entregas duplicadas.
Suporte à entrega exatamente uma vez nas bibliotecas de cliente
As bibliotecas de cliente compatíveis têm uma interface para confirmação com resposta (exemplo: Go). Use essa interface para verificar se a solicitação de confirmação foi bem-sucedida. Se a solicitação de confirmação for bem-sucedida, os clientes terão a garantia de não receber um reenvio. Se a solicitação de confirmação falhar, os clientes poderão esperar uma nova entrega.
Os clientes também podem usar as bibliotecas de cliente compatíveis sem a interface de confirmação. No entanto, nesses casos, as falhas de confirmação podem levar a reentregas silenciosas de mensagens.
As bibliotecas de cliente compatíveis têm interfaces para definir o tempo mínimo de extensão de alocação (exemplo: Go). Defina o valor da extensão mínima de locação como um número alto para evitar qualquer expiração de confirmação relacionada à rede. O valor máximo é definido como 600 segundos.
Os valores e o intervalo padrão das variáveis relacionadas à entrega única, e os nomes das variáveis podem ser diferentes entre as bibliotecas de cliente. Por exemplo, na biblioteca de cliente Java, as variáveis a seguir controlam o envio único.
Variável | Descrição | Valor |
---|---|---|
setEnableExactlyOnceDelivery |
Ativa ou desativa o envio único. | verdadeiro ou falso Padrão=false |
minDurationPerAckExtension |
O tempo mínimo em segundos a ser usado para estender o prazo de confirmação da modificação. | Intervalo=0 a 600 Padrão=nenhum |
maxDurationPerAckExtension |
O tempo máximo em segundos a ser usado para estender o prazo de confirmação da modificação. | Intervalo=0 a 600 Padrão=nenhum |
No caso de entrega única, a solicitação modifyAckDeadline
ou acknowledgment
para o Pub/Sub falha quando o ID de confirmação já expirou. Nesses
casos, o serviço considera o ID de confirmação expirado como inválido, porque uma
entrega mais recente já está em andamento. Isso é feito por design para
entrega única. Em seguida, você verá as solicitações acknowledgment
e ModifyAckDeadline
retornarem uma
resposta INVALID_ARGUMENT
. Quando a entrega "exatamente uma" está desativada, essas
solicitações retornam OK
no caso de IDs de confirmação expiradas.
Para garantir que as solicitações acknowledgment
e ModifyAckDeadline
tenham IDs de confirmação válidos, considere definir o valor de minDurationPerAckExtension
como um número alto.
Crie assinaturas com entrega única
É possível criar uma assinatura com entrega única usando o console do Google Cloud, a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub.
Assinatura de pull
Console
Para criar uma assinatura de pull com entrega exatamente uma vez, siga estas etapas:
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 Entrega exatamente uma vez, selecione Ativar a exibição exatamente uma vez.
Clique em Criar.
gcloud
Para criar uma assinatura de pull com entrega exatamente uma vez, use o comando
gcloud pubsub subscriptions create
com a sinalização --enable-exactly-once-delivery
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --enable-exactly-once-delivery
Substitua:
- SUBSCRIPTION_ID: o ID da assinatura a ser criada
- TOPIC_ID: o ID do tópico a ser anexado à assinatura
REST
Para criar uma assinatura com entrega única, use o
método
projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Substitua:
- PROJECT_ID: o ID do projeto para criar a assinatura
- SUBSCRIPTION_ID: o ID da assinatura a ser criada
Para criar uma assinatura de pull com entrega exatamente uma vez, especifique isto no corpo da solicitação:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "enableExactlyOnceDelivery": true, }
Substitua:
- PROJECT_ID: o ID do projeto com o tópico
- TOPIC_ID: o ID do tópico a ser anexado à assinatura
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.
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.
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.
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.
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.
Assine com entrega de mensagens exatamente uma vez
Veja a seguir alguns exemplos de código para assinar com entrega exatamente uma vez usando a biblioteca de cliente.
Assinatura de pull
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 Pub/Sub Go.
Para se 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 Pub/Sub Java.
Para se 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 Pub/Sub Node.js.
Para se 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 Pub/Sub PHP.
Para se 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 Pub/Sub Python.
Para se 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 Pub/Sub Ruby.
Para se autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
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 Pub/Sub C++.
Para se autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
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 Pub/Sub C#.
Para se 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 (TypeScript)
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 para Node.js.
Para se autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Monitorar assinaturas de entrega única
A métrica subscription/exactly_once_warning_count
registra o número de eventos que podem levar a possíveis reenvios (válidos ou duplicados). Essa métrica conta as
vezes que o Pub/Sub não processa solicitações associadas a
IDs de confirmação (solicitação ModifyAckDeadline
ou acknowledgment
). Os motivos da falha podem ser baseados no servidor ou no cliente. Por exemplo, se a camada de persistência
usada para manter as informações de entrega "exatamente uma vez" estiver indisponível, ele
será um evento baseado no servidor. Se o cliente tentar confirmar uma mensagem com um ID de confirmação inválido, ele será um evento baseado no cliente.
Entender a métrica
subscription/exactly_once_warning_count
captura eventos que podem ou não levar a reenvios reais e podem apresentar ruído, com base no comportamento do cliente. Por exemplo: solicitações acknowledgment
ou ModifyAckDeadline
repetidas com IDs de confirmação inválidos incrementam a métrica repetidamente.
As métricas a seguir também são úteis para entender o comportamento do cliente:
A métrica
subscription/expired_ack_deadlines_count
mostra o número de expirações do ID de confirmação. A expiração do ID de confirmação pode levar a falhas para as solicitaçõesModifyAckDeadline
eacknowledgment
.A métrica
service.serviceruntime.googleapis.com/api/request_count
pode ser usada para capturar falhas de solicitaçõesModifyAckDeadline
ouacknowledgment
nos casos em que as solicitações chegam ao Google Cloud, mas não ao Pub/Sub. Há falhas que essa métrica não captura. Por exemplo, quando os clientes são desconectados do Google Cloud.
Na maioria dos casos de eventos de falha que podem ser repetidos, as bibliotecas de cliente compatíveis refazem a solicitação automaticamente.
Cotas
Assinaturas de envio único estão sujeitas a outros requisitos de cota. Essas cotas são aplicadas em:
- Número de mensagens consumidas de assinaturas com entrega exatamente uma vez ativada por região.
- Número de mensagens confirmadas ou com prazo estendido ao usar assinaturas com entrega exatamente uma vez ativada por região.
Para mais informações sobre essas cotas, consulte a tabela no tópico Cotas.
Entrega exatamente uma vez e assinaturas solicitadas
O Pub/Sub é compatível com a entrega exatamente uma vez com entrega solicitada.
Ao usar o pedido com entrega exatamente uma vez, o Pub/Sub espera que as confirmações estejam em ordem. Se as confirmações estiverem fora de ordem, o serviço vai falhar as solicitações com erros temporários. Se o prazo de confirmação expirar antes de uma confirmação em ordem para a entrega, o cliente receberá uma nova entrega da mensagem. Por isso, quando você usa a ordenação com entrega exatamente uma vez, a capacidade de processamento do cliente fica limitada a uma ordem de mil mensagens por segundo.
Entregas e assinaturas de push exatamente uma vez
O Pub/Sub oferece suporte à entrega exatamente uma vez com assinaturas de pull.
Os clientes que consomem mensagens das assinaturas de push as reconhecem respondendo às solicitações de push com uma resposta bem-sucedida. No entanto, os clientes não sabem se a assinatura do Pub/Sub recebeu e processou a resposta. Isso é diferente das assinaturas de pull, em que as solicitações de confirmação são iniciadas pelos clientes e a assinatura do Pub/Sub responde se a solicitação foi processada com êxito. Por isso, a semântica de entrega "exatamente uma vez" não se alinha bem com assinaturas de push.
Informações úteis
Se o prazo de confirmação não for especificado no momento de CreateSubscription, as assinaturas ativadas para entrega exata terão um prazo de confirmação padrão de 60 segundos.
Prazos mais longos de confirmação padrão são benéficos para evitar o reenvio causado por eventos de rede. As bibliotecas de cliente compatíveis não usam o prazo padrão de confirmação de assinatura.
As assinaturas de entrega única têm uma latência significativamente maior da publicação para a assinatura em comparação com as assinaturas regulares.
Se você precisar de alta capacidade, seus clientes de entrega "exatamente uma vez" também precisarão usar pull de streaming.
Uma assinatura pode receber várias cópias da mesma mensagem devido a cópias do lado da publicação, mesmo que a entrega "exatamente uma vez" esteja ativada. As cópias da publicação podem ocorrer devido a várias novas tentativas únicas de publicação realizadas pelo cliente de publicação ou pelo serviço do Pub/Sub. Várias publicações exclusivas pelo cliente de publicação em várias tentativas resultam em reenvios com diferentes IDs de mensagem. Para responder a uma solicitação de publicação do cliente, várias publicações exclusivas do serviço Pub/Sub geram reenvios com os mesmos IDs de mensagem.
É possível repetir falhas em
subscription/exactly_once_warning_count
, e as bibliotecas de cliente compatíveis fazem novas tentativas automaticamente. No entanto, falhas relacionadas a IDs de confirmação inválidos não podem ser repetidas.