Este documento apresenta uma visão geral de uma assinatura de pull, o fluxo de trabalho dela e as propriedades associadas.
Em uma assinatura por pull, o cliente assinante solicita mensagens do servidor do Pub/Sub.
O modo de 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 síncrono e assíncrono.
Antes de começar
Antes de ler este documento, confira se você conhece os seguintes tópicos:
Como o Pub/Sub funciona e os diferentes termos do Pub/Sub.
Os diferentes tipos de assinatura com suporte do Pub/Sub e por que usar um comando assinatura.
Fluxo de trabalho da assinatura de pull
Para 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 de 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 pull de streaming internamente e envia mensagens de forma assíncrona. Para um cliente de 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 envio (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 de assinante e uma assinatura de pull.
Fluxo de trabalho de pull
O fluxo de trabalho de pull é o seguinte e faz referência à Figura 1:
- O cliente do assinante chama explicitamente o método
pull
, que solicita mensagens para entrega. Essa solicitação é oPullRequest
, conforme mostrado no imagem. O servidor do Pub/Sub responde com zero ou mais mensagens e de confirmação de identidade. Uma resposta sem mensagens ou com erro não indicar que não há mensagens disponíveis para serem recebidas. Essa resposta é o
PullResponse
, conforme mostrado na imagem.O cliente do 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 por streaming, o cliente assinante pode ter várias respostas retornadas devido à conexão aberta. Por outro lado, apenas uma resposta é retornados para cada solicitação de envio.
Propriedades de uma assinatura de pull
As propriedades configuradas para uma assinatura de pull determinam como você escreve mensagens na assinatura. Para mais informações, consulte propriedades da assinatura.
APIs do serviço Pub/Sub
A assinatura de pull do Pub/Sub pode usar um dos duas APIs a seguir para recuperar mensagens:
- Pull
- StreamingPull
Usar RPCs unary Recognition e modifiqueAckDelay ao receber mensagens usando essas APIs. As duas APIs do Pub/Sub são descritas nas guias seguintes.
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 aconteça, é 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 se tornam disponíveis. Confira a seguir 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 novamente os erros de cota automaticamente.
Se não houver erro ou se a cota de conexão estiver disponível novamente, o servidor envia continuamente mensagens para o cliente conectado.
Se ou quando a cota de capacidade for excedida, o servidor interromperá o envio mensagens. No entanto, a conexão não é interrompida. Sempre que houver espaço suficiente cota de capacidade disponível novamente, o stream é retomado.
A conexão é eventualmente encerrada pelo cliente ou pelo servidor.
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 serão enviadas para a conexão quando estiverem disponíveis. O StreamingPull Assim, a API minimiza a latência e maximiza a capacidade de processamento das mensagens.
Leia mais sobre os métodos RPC de StreamingPull: StreamingPullRequest e StreamingPullResponse.
API Pull
Essa API é uma RPC unária tradicional baseada em uma solicitação e uma resposta um modelo de machine learning. Uma única resposta de pull 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 recurso esgotado.
Se não houver erro ou se a cota de capacidade de processamento estiver disponível novamente, o servidor vai responder com zero ou mais mensagens e IDs de confirmação.
Ao usar a API de extração unária, uma resposta com zero mensagens ou com um erro não indica necessariamente que não há mensagens disponíveis para receber.
Usar a API Pull não garante baixa latência e uma alta capacidade de mensagens. Para conseguir alto rendimento e baixa latência com a API Pull, você precisa ter várias solicitações pendentes ao mesmo tempo. Novas solicitações são criadas quando as antigas recebem uma resposta. Arquitetar essa solução sujeitos a erros e difíceis de manter. Recomendamos que você use a API StreamingPull para esses casos de uso.
Só use a API Pull em vez da API StreamingPull se você precisar de aplicações controle sobre o seguinte:
- O número de mensagens que o cliente assinante pode processar
- A memória e os recursos do cliente
Você também pode usar essa API quando seu assinante for um proxy entre o Pub/Sub e outro serviço que opera em uma orientada por pull.
Leia mais sobre os métodos REST de pull: Método: projects.subscriptions.pull.
Leia mais sobre os métodos de Pull RPC: PullRequest e PullResponse.
Tipos de modos de processamento de mensagens
Escolha um dos seguintes modos de pull para os clientes de assinantes.
Modo pull assíncrono
O modo de pull assíncrono separa o recebimento de mensagens do processamento de mensagens em um cliente assinante. Esse modo é o padrão para a maioria dos clientes de assinantes. O modo de pull assíncrono pode usar a API StreamingPull ou a API de pull unária. O pull assíncrono também pode usar a biblioteca de cliente de alto nível de nível inferior ou de baixo nível gerada automaticamente.
Saiba mais sobre as bibliotecas de cliente posteriormente neste documento.
Modo pull síncrono
No modo pull síncrono, o recebimento e o processamento de mensagens ocorrem em e não são desacoplados umas das outras. Portanto, semelhante ao StreamingPull em comparação com APIs unary pull, o processamento assíncrono oferece menor latência e maior capacidade do que o processamento síncrono.
Use o modo pull síncrono somente para aplicativos em que a baixa latência e capacidade de processamento não são os fatores mais importantes e cumprimento de requisitos regulatórios. 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 preciso sobre a memória, a rede ou a CPU. Nesses casos, use o modo síncrono com a API de extração unária.
Bibliotecas de cliente do Pub/Sub
O Pub/Sub oferece um conjunto de dados biblioteca de cliente.
Biblioteca de cliente do Pub/Sub de alto nível
A biblioteca de cliente de alto nível fornece opções para controlar os prazos de confirmação usando o gerenciamento de locação. Essas opções são mais granular 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 a recursos como envio ordenado, envio exatamente uma vez e controle de fluxo.
Recomendamos usar pull assíncrono e a API StreamingPull com o biblioteca de cliente de alto nível. Nem todas as linguagens com suporte para o Google Cloud também oferecem suporte à API de 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 em nível baixo
Uma biblioteca de cliente de baixo nível está disponível para os casos em que você precisa usar o Extrair API 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 solicitada, entrega única, controle de fluxo e gerenciamento de locação quando você usa a biblioteca de cliente de baixo nível gerada automaticamente.
É possível usar o modelo de processamento síncrono quando você usa a biblioteca de cliente gerada automaticamente de baixo nível para todas as linguagens com suporte. Você pode usar a biblioteca de cliente gerada automaticamente em nível baixo e o pull síncrono em casos em que usar a API Pull diretamente faz sentido. 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 Visão geral das APIs do Pub/Sub.
Exemplos de código da biblioteca de cliente
Exemplos de código de 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.
Recupere atributos personalizados usando a biblioteca de cliente de alto nível
Os exemplos a seguir mostram como extrair mensagens de forma 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.
Processar erros usando a biblioteca de cliente de alto nível
Os exemplos a seguir mostram como lidar com erros que surgem ao inscrever-se 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.
Exemplos de código de pull unário
Confira um exemplo de código para enviar por 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#.
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 as ordena a mesma chave de ordem. Confira a seguir algumas advertências importantes:
Definir um valor para
max_messages
na solicitação não garante quemax_messages
sejam retornados, mesmo que haja essa quantidade de mensagens na pendências. A API Pull do Pub/Sub pode retornar menos demax_messages
para reduzir a latência de entrega de mensagens que estão prontas para serem entregues.Uma resposta de pull com 0 mensagens não pode ser usada como um indicador de que não há mensagens no backlog. É possível receber uma resposta com 0 mensagens e receber 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 ao mesmo tempo. Conforme a capacidade de processamento do tópico aumentar, mais solicitações de pull serão necessárias. Em geral, o modo StreamingPull é preferível 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 o tópico.
Crie ou modifique uma assinatura com a gcloud CLI.
Crie ou modifique uma assinatura com as APIs REST.
Crie ou modifique uma assinatura com as APIs RPC.