Este documento descreve como receber mensagens de uma subscrição de obtenção. Pode usar a Trusted Cloud consola, a CLI do Google Cloud, a biblioteca cliente ou a API Pub/Sub para criar uma subscrição de obtenção.
Antes de começar
- Crie uma subscrição de obtenção.
Funções e autorizações necessárias
Para receber as autorizações de que
precisa para obter mensagens de subscrições e geri-las,
peça ao seu administrador para lhe conceder a
função IAM Subscritor do Pub/Sub (roles/pubsub.subscriber
)
no projeto.
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Esta função predefinida contém as autorizações necessárias para obter mensagens de subscrições e geri-las. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias
São necessárias as seguintes autorizações para obter mensagens de subscrições e geri-las:
-
Extrair de uma subscrição:
pubsub.subscriptions.consume
-
Crie uma subscrição:
pubsub.subscriptions.create
-
Elimine uma subscrição:
pubsub.subscriptions.delete
-
Obtenha uma subscrição:
pubsub.subscriptions.get
-
Anuncie uma subscrição:
pubsub.subscriptions.list
-
Atualize uma subscrição:
pubsub.subscriptions.update
-
Anexe uma subscrição a um tópico:
pubsub.topics.attachSubscription
-
Obtenha a Política IAM para uma subscrição:
pubsub.subscriptions.getIamPolicy
-
Configure a política IAM para uma subscrição:
pubsub.subscriptions.setIamPolicy
-
Conceda a autorização para consumir mensagens de uma subscrição na subscrição pull:
pubsub.subscriptions.consume
Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.
Extraia uma mensagem de uma subscrição
Os exemplos seguintes demonstram como obter uma mensagem de uma subscrição usando a API StreamingPull ou a API Pull.
API StreamingPull
Para usar a API StreamingPull, tem de usar uma biblioteca cliente.
A Trusted Cloud consola e a CLI gcloud não suportam a API StreamingPull.
StreamingPull e exemplos de código de bibliotecas clientes de alto nível
C++
Antes de experimentar este exemplo, siga as instruções de configuração do C++ no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.
C#
Antes de experimentar este exemplo, siga as instruções de configuração do C# em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.
Ir
O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
Ruby
O exemplo seguinte usa a biblioteca cliente Ruby Pub/Sub v3. Se ainda estiver a usar a biblioteca v2, consulte o guia de migração para a v3. Para ver uma lista de exemplos de código do Ruby v2, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Ruby em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby Pub/Sub.
Recupere atributos personalizados através da biblioteca de cliente de nível superior
Os exemplos seguintes mostram como obter mensagens de forma assíncrona e recuperar os atributos personalizados dos metadados.
C++
Antes de experimentar este exemplo, siga as instruções de configuração do C++ no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.
C#
Antes de experimentar este exemplo, siga as instruções de configuração do C# em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.
Ir
O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
Ruby
O exemplo seguinte usa a biblioteca cliente Ruby Pub/Sub v3. Se ainda estiver a usar a biblioteca v2, consulte o guia de migração para a v3. Para ver uma lista de exemplos de código do Ruby v2, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Ruby em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby Pub/Sub.
Trate erros com a biblioteca de cliente de nível superior
Os exemplos seguintes mostram como processar erros que surgem quando se subscrevem mensagens.
C++
Antes de experimentar este exemplo, siga as instruções de configuração do C++ no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.
Ir
O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
Ruby
O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.
Tração unária
Para usar a API Unary, pode usar a Trusted Cloud consola, a CLI do Google Cloud ou uma biblioteca cliente.
Considerações
O Pub/Sub envia uma lista de mensagens. Se a lista tiver várias mensagens, o Pub/Sub ordena as mensagens com a mesma chave de ordenação. Seguem-se algumas ressalvas importantes:
A definição de um valor para
max_messages
no pedido não garante que são devolvidosmax_messages
, mesmo que existam essa quantidade de mensagens no registo pendente. A API Pub/Sub Pull pode devolver menos demax_messages
mensagens para reduzir a latência de entrega das mensagens que estão prontamente disponíveis para entrega.Uma resposta de obtenção com 0 mensagens não deve ser usada como um indicador de que não existem mensagens na fila de espera. É possível receber uma resposta com 0 mensagens e ter um pedido subsequente que devolve mensagens.
Consola
Na Trusted Cloud consola, aceda à página Subscrições do Pub/Sub.
Clique no nome da subscrição a partir da qual quer extrair dados.
No separador Mensagens, clique em Extrair.
Deverá ver as mensagens que publicou nesta subscrição e a hora em que foram publicadas.
Quando usa a Trusted Cloud consola com uma subscrição de baixo volume, é possível que um pedido Pull devolva zero mensagens. Isto deve-se ao facto de a consola usar a obtenção unária, que não garante uma latência baixa nem um elevado débito de mensagens. Se não aparecerem mensagens, inicie um novo pedido de obtenção quando as mensagens estiverem disponíveis.
gcloud
Para retirar uma mensagem de uma subscrição, execute o comando gcloud pubsub subscriptions pull
. A CLI gcloud imprime a mensagem na linha de comandos.
gcloud pubsub subscriptions pull SUBSCRIPTION_NAME --auto-ack
Substituição:
SUBSCRIPTION_NAME
: o nome da subscrição da qual quer extrair mensagens.
Bibliotecas cliente
Segue-se um exemplo de código para extrair e confirmar um número fixo de mensagens.
C++
Antes de experimentar este exemplo, siga as instruções de configuração do C++ no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.
C#
Antes de experimentar este exemplo, siga as instruções de configuração do C# em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
PHP
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
Ruby
O exemplo seguinte usa a biblioteca cliente Ruby Pub/Sub v3. Se ainda estiver a usar a biblioteca v2, consulte o guia de migração para a v3. Para ver uma lista de exemplos de código do Ruby v2, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Ruby em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby Pub/Sub.
Protocolo
Pedido:
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"
}
}]
}
Pedido:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
O que se segue?
- Crie ou modifique uma subscrição com
gcloud
comandos. - Crie ou modifique uma subscrição com APIs REST.
- Crie ou modifique uma subscrição com APIs RPC.