Neste documento, descrevemos como criar uma assinatura de push. É possível usar o console do Google Cloud, a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub para criar uma assinatura de push.
Antes de começar
- Saiba mais sobre assinaturas.
- Entenda como funcionam as assinaturas push.
Papéis e permissões necessárias
Para criar uma assinatura, configure o controle de acesso no nível do projeto. Você também precisa de permissões no nível do recurso se as assinaturas e os tópicos estiverem em projetos diferentes, conforme discutido mais adiante nesta seção.
Para ter as permissões necessárias para criar assinaturas de push,
peça ao administrador para conceder a você o
papel do IAM de Editor do Pub/Sub (roles/pubsub.editor
) no projeto.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Esse papel predefinido contém as permissões necessárias para criar assinaturas de push. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para criar assinaturas de push:
-
Criar uma assinatura:
pubsub.subscriptions.create
-
Excluir uma assinatura:
pubsub.subscriptions.delete
-
Fazer uma assinatura:
pubsub.subscriptions.get
-
Listar uma assinatura:
pubsub.subscriptions.list
-
Atualizar uma assinatura:
pubsub.subscriptions.update
-
Anexar uma assinatura a um tópico:
pubsub.topics.attachSubscription
-
Consiga a política do IAM para uma assinatura:
pubsub.subscriptions.getIamPolicy
-
Configure a política do IAM para uma assinatura:
pubsub.subscriptions.setIamPolicy
Talvez você também consiga receber essas permissões com papéis personalizados ou outros papéis predefinidos.
Se você precisar criar assinaturas de push em um projeto que estão associadas a um tópico em outro projeto, peça ao administrador do tópico para conceder a você também o papel do IAM (roles/pubsub.editor)
de Editor do Pub/Sub no tópico.
Propriedades da assinatura de push
Ao configurar uma assinatura de push, é possível especificar as propriedades a seguir.
Propriedades comuns
Saiba mais sobre as propriedades de assinatura comuns que podem ser definidas em todas as assinaturas.
Endpoints
URL do endpoint (obrigatório). Um endereço HTTPS acessível publicamente. O servidor do endpoint de push precisa ter um certificado SSL válido assinado por uma autoridade de certificação. O serviço do Pub/Sub entrega mensagens para enviar endpoints da mesma região do Google Cloud em que o serviço do Pub/Sub armazena as mensagens. O serviço Pub/Sub entrega mensagens da mesma região do Google Cloud com base no melhor esforço.
O Pub/Sub não exige mais prova de propriedade para domínios de URL de assinatura de push. Se o domínio recebe solicitações POST inesperadas do Pub/Sub, é possível denunciar suspeita de abuso.
Proporção de Eficiência Energética (EER)
Ative a autenticação. Quando ativadas, as mensagens entregues pelo Pub/Sub para o endpoint de push incluem um cabeçalho de autorização para permitir que o endpoint autentique a solicitação. Há mecanismos automáticos de autenticação e autorização disponíveis para endpoints do App Engine Standard e Cloud Functions hospedados no mesmo projeto da assinatura.
A configuração de autenticação de uma assinatura de push autenticada consiste em uma conta serviço gerenciado pelo usuário e nos parâmetros de público que são especificados em uma chamada create, patch ou ModifyPushConfig. Também é preciso conceder a uma conta de serviço especial gerenciada pelo Google um papel específico, conforme discutido na próxima seção.
Conta de serviço gerenciado pelo usuário (obrigatório). A conta de serviço associada à assinatura de push. Esta conta é usada como a declaração
email
do JSON Web Token (JWT) gerado. Esta é uma lista de requisitos para a conta de serviço:Essa conta de serviço precisa estar no mesmo projeto que a assinatura de push.
O principal que está criando ou modificando a assinatura de push precisa ter a permissão
iam.serviceAccounts.actAs
na conta de serviço. É possível conceder um papel com essa permissão no projeto, na pasta ou na organização para permitir que o autor da chamada represente várias contas de serviço ou conceder um papel com essa permissão na conta de serviço para permitir que o autor da chamada represente apenas essa conta de serviço.
Público-alvo. Uma única string indiferente a maiúsculas que o webhook usa para validar o público-alvo desse token específico.
Conta de serviço gerenciado pelo Google (obrigatório).
O Pub/Sub cria automaticamente uma conta de serviço para você com o formato
service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
.Essa conta de serviço precisa receber a permissão
iam.serviceAccounts.getOpenIdToken
(incluída no papelroles/iam.serviceAccountTokenCreator
) para permitir que o Pub/Sub crie tokens JWT para solicitações de push autenticadas.
Desencapsulamento de payload
A opção Ativar desencapsulamento de payload remove todas as mensagens do Pub/Sub de todos os metadados das mensagens, exceto os dados da mensagem. Com o desencapsulamento do payload, os dados da mensagem são entregues diretamente como o corpo HTTP.
- Gravar metadados. Adiciona novamente os metadados removidos das mensagens ao cabeçalho da solicitação.
VPC Service Controls
Para um projeto protegido pelo VPC Service Controls, confira as seguintes limitações para assinaturas de push:
Só é possível criar novas assinaturas de push com o endpoint de push definido como um serviço do Cloud Run com um URL
run.app
padrão ou uma execução do Workflows. Os domínios personalizados não funcionam.Ao rotear eventos pelo Eventarc para destinos do Workflows em que o endpoint de push está definido para uma execução do Workflows, só é possível criar novas assinaturas de push pelo Eventarc.
Não é possível atualizar assinaturas de push existentes. Essas assinaturas de push continuam funcionando, embora não sejam protegidas pelo VPC Service Controls.
Criar uma assinatura de push
Os exemplos a seguir demonstram como criar uma assinatura com entrega por push usando as configurações padrão fornecidas.
Por padrão, as assinaturas usam a entrega por pull, a menos que você defina explicitamente uma configuração de push, conforme mostrado nos exemplos a seguir.
Console
Para criar uma assinatura de push, siga estas etapas:
- No Console do Google Cloud, acesse a página Assinaturas.
- Clique em Criar assinatura.
- No campo ID da assinatura, digite um nome.
Para saber como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
- Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.
- Selecione o Tipo de envio como Push.
- Especifique um URL de endpoint.
- Mantenha todos os outros valores padrão.
- Clique em Criar.
Você também pode criar uma assinatura na seção Tópicos. Esse atalho é útil para associar tópicos a assinaturas.
- No console do Google Cloud, acesse a página Tópicos.
- Clique em more_vert ao lado do tópico em que você quer criar uma assinatura.
- No menu de contexto, selecione Criar assinatura.
- Insira o ID da assinatura.
Para saber como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
- Selecione o Tipo de envio como Push.
- Especifique um URL de endpoint.
- Mantenha todos os outros valores padrão.
- Clique em Criar.
gcloud
-
No Console do Google Cloud, ative o Cloud Shell.
Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
-
Para criar uma assinatura de push, execute o comando
gcloud pubsub subscriptions create
.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT
Substitua:
SUBSCRIPTION_ID
: o nome ou ID da nova assinatura de push.TOPIC_ID
: o nome ou ID do tópico.- PUSH_ENDPOINT: o URL a ser usado como o endpoint para esta assinatura.
Por exemplo,
https://myproject.appspot.com/myhandler
.
REST
Para criar uma assinatura de push, use o
método
projects.subscriptions.create
:
Solicitação:
A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization
. Para conseguir um token de acesso para o Application Default Credentials atual, use: gcloud auth application-default print-access-token.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer ACCESS_TOKEN
Corpo da solicitação:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", // Only needed if you are using push delivery "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" } }
Em que:
https://myproject.appspot.com/myhandler
.Resposta:
{ "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler", "attributes": { "x-goog-version": "v1" } }, "ackDeadlineSeconds": 10, "messageRetentionDuration": "604800s", "expirationPolicy": { "ttl": "2678400s" } }
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 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, acesse Configurar a autenticação para bibliotecas de cliente.
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, acesse Configurar a autenticação para bibliotecas de cliente.
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, acesse Configurar a autenticação para bibliotecas de cliente.
Node.js
Node.js
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, acesse Configurar a autenticação para bibliotecas de cliente.
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, acesse Configurar a autenticação para bibliotecas de cliente.
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, acesse Configurar a autenticação para bibliotecas de cliente.
A seguir
- Crie ou modifique uma assinatura com comandos do
gcloud
. - Crie ou modifique uma assinatura com APIs REST.