Neste documento, apresentamos uma visão geral de uma assinatura de pull, do fluxo de trabalho dela e das propriedades associadas.
Em uma assinatura de 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. Também é possível escolher entre o processamento de mensagens assíncrono e síncrono.
Antes de começar
Antes de ler este documento, certifique-se de que você conheça o seguinte:
Como funciona o Pub/Sub e os diferentes termos do Pub/Sub.
Os diferentes tipos de assinaturas compatíveis com o Pub/Sub e por que usar uma assinatura de pull.
Fluxo de trabalho da assinatura de pull
Para uma assinatura de pull, o cliente assinante inicia solicitações a 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 executa solicitações de envio de streaming internamente e entrega mensagens de maneira 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 gerada automaticamente. Essa biblioteca faz solicitações de pull ou 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 pull.
Fluxo de trabalho de pull
O fluxo de trabalho pull é o seguinte e referencia a Figura 1:
- O cliente do 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. Por outro lado, apenas uma resposta é retornada para cada solicitação de envio.
Propriedades de uma assinatura de pull
As propriedades configuradas para uma assinatura de pull determinam como você grava mensagens na assinatura. Para mais informações, consulte as propriedades da assinatura.
APIs de serviço do Pub/Sub
A assinatura de pull do Pub/Sub pode usar uma das duas APIs a seguir para recuperar mensagens:
- Pull
- StreamingPull
Use RPCs unary Confirm eModifyAckTimestamp ao receber mensagens usando essas APIs. As duas APIs Pub/Sub são descritas nas guias 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. Talvez você nunca use a API StreamingPull diretamente, mas é importante saber as diferenças dela em relação à API Pull.
A API StreamingPull depende de uma conexão bidirecional permanente para receber várias mensagens à medida que elas se tornam disponíveis. Veja a seguir 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 retornará um erro de recurso esgotado. A biblioteca de cliente tenta de novo os erros de fora da 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 for excedida, o servidor interromperá o envio de mensagens. No entanto, a conexão não está interrompida. Sempre que houver cota de capacidade suficiente disponível novamente, o stream será retomado.
O cliente ou o servidor finalmente encerra a conexão.
A API StreamingPull mantém uma conexão aberta. Os servidores do Pub/Sub fecham periodicamente a conexão 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 das mensagens.
Leia mais sobre os métodos REST do StreamingPull: StreamingPullRequest e StreamingPullResponse.
Leia mais sobre os métodos de RPC do StreamingPull: StreamingPullRequest e StreamingPullResponse.
API Pull
Essa API é uma RPC unária tradicional baseada em um modelo de solicitação e resposta. Uma única resposta de envio 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 for excedida, o servidor retornará um erro de recurso esgotado.
Se não houver erro ou a cota de capacidade estiver disponível novamente, o servidor responderá a zero ou mais mensagens e IDs de confirmação.
Ao usar a API Pull unary, 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 uma alta capacidade de mensagens. Para alcançar alta capacidade e baixa latência com a API Pull, você precisa ter várias solicitações pendentes simultâneas. As novas solicitações são criadas quando as antigas recebem uma resposta. Arquitetar essa solução é propenso a erros e difícil de manter. Recomendamos o uso da API StreamingPull para esses casos de uso.
Use a API Pull em vez da API StreamingPull somente se você precisar de um controle rigoroso 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 para pull.
Leia mais sobre os métodos REST de Pull: Method: projects.subscriptions.pull.
Leia mais sobre os métodos de RPC pull: PullRequest e PullResponse.
Tipos de modos de processamento de mensagens
Escolha um dos seguintes modos de pull para seus clientes assinantes.
Modo de pull assíncrono
O modo pull assíncrono dissocia o recebimento de mensagens do processamento de mensagens em um cliente assinante. Esse modo é o padrão para a maioria dos clientes assinantes. O modo pull 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 de baixo nível gerada automaticamente.
Você pode saber mais sobre bibliotecas de cliente posteriormente neste documento.
Modo de tração síncrono
No modo pull síncrono, o recebimento e o processamento de mensagens ocorrem em sequência e não são separados um do outro. Portanto, de maneira semelhante às APIs StreamingPull em comparação com as APIs Pull unárias, o processamento assíncrono oferece menor latência e maior capacidade do que o síncrono.
Use o modo pull síncrono somente para aplicativos em que baixa latência e alta capacidade não são os fatores mais importantes em comparação com alguns outros requisitos. Por exemplo, um aplicativo pode usar apenas o modelo de programação síncrona. Ou um aplicativo com restrições de recursos pode exigir um controle mais exato sobre a memória, a rede ou a 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 do Pub/Sub de alto nível
A biblioteca de cliente de alto nível oferece opções para controlar os prazos de confirmação usando o gerenciamento de lease. 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 de assinatura. A biblioteca de cliente de alto nível também implementa o suporte a recursos como entrega ordenada, entrega exata e controle de fluxo.
Recomendamos o uso de pull assíncrono e a API StreamingPull com a biblioteca de cliente de alto nível. Nem todas as linguagens compatíveis com o 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 gerada automaticamente de nível inferior
Uma biblioteca de cliente de baixo nível está disponível para casos em que é preciso usar a API Pull diretamente. Você pode usar o processamento síncrono ou assíncrono com a biblioteca de cliente de baixo nível gerada automaticamente. É preciso codificar manualmente os recursos, como entrega solicitada, entrega única, controle de fluxo e gerenciamento de locação, ao usar a biblioteca de cliente gerada automaticamente de baixo nível.
Você pode usar o modelo de processamento síncrono ao utilizar a biblioteca de cliente de baixo nível gerada automaticamente para todas as linguagens compatíveis. É possível usar a biblioteca de cliente gerada automaticamente de baixo nível e o pull síncrono nos casos em que o uso direto da API Pull faz sentido. Por exemplo, você pode ter uma lógica de aplicativo atual que dependa desse modelo.
Para usar diretamente as bibliotecas de cliente geradas automaticamente de baixo nível, consulte a visão geral das APIs do Pub/Sub.
Exemplos de código da biblioteca de cliente
Exemplos de código da biblioteca de cliente de alto nível e StreamingPull
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.
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.
Recuperar atributos personalizados usando a biblioteca de cliente de alto nível
Os exemplos a seguir mostram como enviar mensagens por pull de maneira assíncrona e recuperar os atributos personalizados dos metadados.
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.
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.
Tratar erros usando a biblioteca de cliente de alto nível
Os exemplos a seguir mostram como processar erros que podem ocorrer durante a inscrição em mensagens.
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.
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 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.
Amostras de código pull unário
Veja um exemplo de código para pull e confirmar um número fixo de mensagens.
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++.
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#.
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 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.
Protocolo
Solicitação:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
Resposta:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
Solicitação:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
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.
O Pub/Sub entrega uma lista de mensagens. Se a lista tiver várias mensagens, o Pub/Sub vai ordenar as mensagens com a mesma chave de ordem. Veja a seguir algumas advertências importantes:
Definir um valor para
max_messages
na solicitação não garante quemax_messages
seja retornado, mesmo que haja muitas mensagens no backlog. A API Pull do Pub/Sub pode retornar menos quemax_messages
para reduzir a latência de entrega de mensagens que estão prontamente disponíveis para serem entregues.Uma resposta de pull que vem com 0 mensagens não pode ser usada como um indicador de que não há mensagens no backlog. É possível receber uma resposta sem mensagens e ter uma solicitação subsequente que retorne mensagens.
Para alcançar baixa latência de entrega de mensagens com o modo pull unário, é essencial ter muitas solicitações de envio pendentes simultaneamente. À medida que a capacidade do tópico aumenta, mais solicitações de envio são necessárias. Em geral, o modo StreamingPull é indicado para aplicativos sensíveis à latência.
Cotas e limites
As conexões Pull e StreamingPull estão sujeitas a cotas e limites. Para mais informações, consulte Cotas e limites do Pub/Sub.
A seguir
Crie uma assinatura de pull para seu tópico.
Crie ou modifique uma assinatura com a CLI gcloud.
Crie ou modifique uma assinatura com APIs REST.
Crie ou modifique uma assinatura com APIs RPC.