Este documento apresenta uma visão geral de uma assinatura por pull, do fluxo de trabalho dela e das propriedades associadas.
Em uma assinatura por pull, um cliente assinante solicita mensagens do servidor do Pub/Sub.
O modo pull pode usar uma das duas APIs de serviço, Pull ou StreamingPull. Para executar a API escolhida, selecione uma biblioteca de cliente de alto nível fornecida pelo Google ou uma biblioteca de cliente de baixo nível gerada automaticamente. Você também pode escolher entre o processamento de mensagens assíncrono e síncrono.
Antes de começar
Antes de ler este documento, confira se você conhece os seguintes conceitos:
Como o Pub/Sub funciona e os diferentes termos do Pub/Sub.
Os diferentes tipos de assinaturas que o Pub/Sub aceita e por que você pode querer usar uma assinatura de extração.
Fluxo de trabalho de assinatura de pull
Em uma assinatura de pull, o cliente assinante inicia solicitações para um servidor do Pub/Sub para recuperar mensagens. O cliente assinante usa uma das seguintes APIs:
A maioria dos clientes assinantes não faz essas solicitações diretamente. Em vez disso, os clientes dependem da biblioteca de cliente de alto nível fornecida pelo Google Cloud, que realiza solicitações de pull de streaming internamente e entrega mensagens de forma assíncrona. Para um cliente assinante que precisa de mais controle sobre como as mensagens são extraídas, o Pub/Sub usa uma biblioteca gRPC de baixo nível e gerada automaticamente. Essa biblioteca faz solicitações de extração ou de extração por streaming diretamente. Essas solicitações podem ser síncronas ou assíncronas.
As duas imagens a seguir mostram o fluxo de trabalho entre um cliente assinante e uma assinatura de extração.


Fluxo de trabalho de pull
O fluxo de trabalho de extração é o seguinte e faz referência à Figura 1:
- O cliente assinante chama explicitamente o método
pull
, que solicita mensagens para entrega. Essa solicitação é oPullRequest
, conforme mostrado na imagem. O servidor do Pub/Sub responde com zero ou mais mensagens e IDs de confirmação. Uma resposta com zero mensagens ou com um erro não indica necessariamente que não há mensagens disponíveis para receber. Essa resposta é o
PullResponse
, conforme mostrado na imagem.O cliente assinante chama explicitamente o método
acknowledge
. O cliente usa o ID de confirmação retornado para confirmar que a mensagem foi processada e não precisa ser entregue novamente.
Para uma única solicitação de envio de streaming, um cliente assinante pode ter várias respostas retornadas devido à conexão aberta. Em contraste, apenas uma resposta é retornada para cada solicitação de envio.
Propriedades de uma assinatura por pull
As propriedades configuradas para uma assinatura de pull determinam como você grava mensagens na assinatura. Para mais informações, consulte propriedades de assinatura.
APIs de serviço do Pub/Sub
A assinatura por pull do Pub/Sub pode usar uma das duas APIs a seguir para recuperar mensagens:
- Pull
- StreamingPull
Use RPCs unários Acknowledge e ModifyAckDeadline ao receber mensagens usando essas APIs. As duas APIs Pub/Sub são descritas nas seções a seguir.
API StreamingPull
Sempre que possível, as bibliotecas de cliente do Pub/Sub usam StreamingPull para máxima capacidade e menor latência. Embora seja possível que o uso da API StreamingPull diretamente nunca venha a acontecer, é importante saber como ela difere da API Pull.
A API StreamingPull depende de uma conexão bidirecional persistente para receber várias mensagens à medida que elas são disponibilizadas. Este é o fluxo de trabalho:
O cliente envia uma solicitação ao servidor para estabelecer uma conexão. Se a cota de conexão for excedida, o servidor vai retornar um erro de recurso esgotado. A biblioteca de cliente tenta novamente os erros de falta de cota automaticamente.
Se não houver erro ou se a cota de conexão estiver disponível novamente, o servidor enviará mensagens continuamente para o cliente conectado.
Se ou quando a cota de capacidade de processamento for excedida, o servidor vai parar de enviar mensagens. No entanto, a conexão não é interrompida. Quando houver de novo uma cota de capacidade de processamento suficiente, o stream será retomado.
O cliente ou o servidor encerra a conexão.
A API StreamingPull mantém uma conexão aberta. Os servidores do Pub/Sub fecham a conexão recorrentemente após um período para evitar uma conexão fixa de longa duração. A biblioteca de cliente reabre automaticamente uma conexão StreamingPull.
As mensagens são enviadas para a conexão quando estão disponíveis. Assim, a API StreamingPull minimiza a latência e maximiza a capacidade de processamento das mensagens.
Leia mais sobre os métodos RPC StreamingPull: StreamingPullRequest e StreamingPullResponse.
API Pull
Essa API é um RPC unário tradicional baseado em um modelo de solicitação e resposta. Uma única resposta de extração corresponde a uma única solicitação de envio. Este é o fluxo de trabalho:
O cliente envia uma solicitação de mensagens ao servidor. Se a cota de capacidade de processamento for excedida, o servidor vai retornar um erro de recurso esgotado.
Se não houver erro ou se a cota de capacidade de processamento estiver disponível novamente, o servidor responderá com zero ou mais mensagens e IDs de confirmação.
Ao usar a API Pull unária, uma resposta com zero mensagens ou com um erro não indica necessariamente que não há mensagens disponíveis para receber.
O uso da API Pull não garante baixa latência e alta taxa de transferência de mensagens. Para conseguir alta capacidade de processamento e baixa latência com a API Pull, você precisa ter várias solicitações pendentes simultâneas. Novas solicitações são criadas quando as antigas recebem uma resposta. Arquitetar uma solução assim é propenso a erros e difícil de manter. Recomendamos usar a API StreamingPull para esses casos de uso.
Use a API Pull em vez da API StreamingPull somente se você precisar de controle estrito sobre o seguinte:
- O número de mensagens que o cliente assinante pode processar
- A memória e os recursos do cliente
Também é possível usar essa API quando o assinante é um proxy entre o Pub/Sub e outro serviço que opera de maneira mais orientada a pull.
Leia mais sobre os métodos REST de pull: Método: projects.subscriptions.pull.
Leia mais sobre os métodos Pull RPC: PullRequest e PullResponse.
Tipos de modos de processamento de mensagens
Escolha um dos seguintes modos de extração para os clientes assinantes.
Modo de pull assíncrono
O modo de recebimento assíncrono separa o recebimento do processamento de mensagens em um cliente assinante. Esse modo é o padrão para a maioria dos clientes assinantes. O modo de extração assíncrono pode usar a API StreamingPull ou a API Pull unária. O pull assíncrono também pode usar a biblioteca de cliente de alto nível ou a biblioteca de cliente de baixo nível gerada automaticamente.
Você vai saber mais sobre as bibliotecas de cliente mais adiante neste documento.
Modo de pull síncrono
No modo de extração síncrona, o recebimento e o processamento de mensagens ocorrem em sequência e não são separados. Portanto, assim como as APIs StreamingPull e Pull unárias, o processamento assíncrono oferece menor latência e maior capacidade do que o processamento síncrono.
Use o modo de extração síncrona apenas para aplicativos em que a baixa latência e a alta capacidade de processamento não são os fatores mais importantes em comparação com outros requisitos. Por exemplo, um aplicativo pode ser limitado a usar apenas o modelo de programação síncrona. Ou um aplicativo com restrições de recursos pode exigir um controle mais exato sobre memória, rede ou CPU. Nesses casos, use o modo síncrono com a API Pull unária.
Bibliotecas de cliente do Pub/Sub
O Pub/Sub oferece uma biblioteca de cliente de alto e baixo nível gerada automaticamente.
Biblioteca de cliente de alto nível do Pub/Sub
A biblioteca de cliente de alto nível oferece opções para controlar os prazos de confirmação usando o gerenciamento de concessão. Essas opções são mais granulares do que quando você configura os prazos de confirmação usando o console ou a CLI no nível da assinatura. A biblioteca de cliente de alto nível também implementa suporte para recursos como entrega ordenada, entrega exatamente uma vez e controle de fluxo.
Recomendamos usar o pull assíncrono e a API StreamingPull com a biblioteca de cliente de alto nível. Nem todas as linguagens compatíveis com Google Cloud também são compatíveis com a API Pull na biblioteca de cliente de alto nível.
Para usar as bibliotecas de cliente de alto nível, consulte Bibliotecas de cliente do Pub/Sub.
Biblioteca de cliente do Pub/Sub de baixo nível gerada automaticamente.
Uma biblioteca de cliente de baixo nível está disponível para casos em que é necessário usar a API Pull diretamente. É possível usar o processamento síncrono ou assíncrono com a biblioteca de cliente de baixo nível gerada automaticamente. Você precisa codificar manualmente recursos como entrega ordenada, entrega exatamente uma vez, controle de fluxo e gerenciamento de concessão ao usar a biblioteca de cliente de baixo nível gerada automaticamente.
É possível usar o modelo de processamento síncrono com a biblioteca de cliente de baixo nível gerada automaticamente para todas as linguagens compatíveis. Você pode usar a biblioteca de cliente de baixo nível gerada automaticamente e o pull síncrono em casos em que faz sentido usar a API Pull diretamente. Por exemplo, você pode ter uma lógica de aplicativo que depende desse modelo.
Para usar diretamente as bibliotecas de cliente de baixo nível geradas automaticamente, consulte a visão geral das APIs do Pub/Sub.
A seguir
Crie uma assinatura de pull para seu tópico.
Solucione problemas com uma assinatura de pull.
Crie ou modifique uma assinatura com a CLI gcloud.
Crie ou modifique uma assinatura com APIs REST.
Crie ou modifique uma assinatura com as APIs RPC.