Este documento descreve como criar uma assinatura push. Você pode usar o 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 as assinaturas push funcionam.
Papéis e permissões necessárias
Para criar uma assinatura, você precisa configurar o controle de acesso no para envolvidos no projeto. Você também precisa de permissões no nível do recurso se suas assinaturas e tópicos estão 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ê
Papel do IAM Editor do Pub/Sub (roles/pubsub.editor
) no projeto.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
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:
-
Crie uma assinatura:
pubsub.subscriptions.create
-
Para excluir uma assinatura:
pubsub.subscriptions.delete
-
Assinar uma assinatura:
pubsub.subscriptions.get
-
Listar uma assinatura:
pubsub.subscriptions.list
-
Atualizar uma assinatura:
pubsub.subscriptions.update
-
Anexe uma assinatura a um tópico:
pubsub.topics.attachSubscription
-
Para receber a política do IAM de uma assinatura:
pubsub.subscriptions.getIamPolicy
-
Configure a política do IAM para uma assinatura:
pubsub.subscriptions.setIamPolicy
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Se você precisar criar modelos de
assinaturas de um projeto que estão associadas a um tópico em outro
projeto, peça ao administrador do tópico para conceder a você o papel Editor do Pub/Sub
(roles/pubsub.editor)
no tópico.
Propriedades da assinatura de push
Ao configurar uma assinatura de push, é possível especificar as seguintes propriedades.
Propriedades comuns
Saiba mais sobre as propriedades comuns de assinatura que podem ser definidas em todas as assinaturas.
Endpoints
URL do endpoint (obrigatório). Um endereço HTTPS de acesso público. O servidor do envio endpoint precisa ter um certificado SSL válido assinado por uma autoridade certificadora. 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 push domínios de URL de assinatura. Se seu domínio recebe solicitações POST inesperadas no Pub/Sub, denuncie a suspeita de abuso.
Autenticação
Ative a autenticação. Quando ativadas, as mensagens entregues pelo Pub/Sub ao endpoint de push incluem um cabeçalho de autorização para para permitir que o endpoint autentique a solicitação. Autenticação automática e Há mecanismos de autorização disponíveis para endpoints das funções do App Engine padrão e do Cloud Run 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 os parâmetros de público-alvo que são especificados em uma criação, patch ou ModifyPushConfig a chamada. Você também precisa conceder um papel específico a um agente de serviço, conforme discutido em na próxima seção.
Conta de serviço gerenciado pelo usuário (obrigatório). A conta de serviço associada ao push assinatura. Essa conta é usada como a declaração
email
do JSON Web Token (JWT) gerado. Confira a seguir 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 organização para permitir que para representar várias contas de serviço ou conceder um papel com este no serviço conta para permitir que o autor da chamada representem apenas essa conta de serviço.
Público. Uma única string que não diferencia maiúsculas de minúsculas usa para validar o público-alvo desse token específico.
Agente de serviço (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
:Esse agente de serviço precisa receber Permissão
iam.serviceAccounts.getOpenIdToken
(incluída noroles/iam.serviceAccountTokenCreator
papel) 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 o Pub/Sub mensagens de todos os metadados da mensagem, exceto os dados da mensagem. Com payload desencapsulamento, os dados da mensagem serão entregues diretamente como o corpo HTTP.
- Gravar metadados. Adiciona os metadados removidos das mensagens de volta ao cabeçalho da solicitação.
VPC Service Controls
Para um projeto protegido por VPC Service Controls observe as seguintes limitações para assinaturas push:
Só é possível criar novas assinaturas de push para as quais o endpoint de push seja definido como um serviço do Cloud Run com um URL
run.app
padrão ou um Execução de Workflows. Os domínios personalizados não funcionam.Ao rotear eventos pelo Eventarc para o Workflows destinos em que o endpoint de push é definido como um Workflows execução, só é possível criar novas assinaturas de push com o Eventarc.
Não é possível atualizar assinaturas de push existentes. Essas assinaturas de push continuam funcionando, mas não são protegidos pelo VPC Service Controls.
Criar uma assinatura por push
Os exemplos a seguir demonstram como criar uma assinatura com push usando as configurações padrão fornecidas.
Por padrão, as assinaturas usam entrega pull, a menos que você defina explicitamente uma configuração de push, como 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.
- Insira um nome no campo ID da assinatura.
Para saber mais sobre 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 Push como Tipo de envio.
- 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 entrega como Push.
- Especifique um URL de endpoint.
- Mantenha todos os outros valores padrão.
- Clique em Criar.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Para criar uma assinatura 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 o ID do novo envio assinatura.TOPIC_ID
: o nome ou o ID do tópico.- PUSH_ENDPOINT: o URL a ser usado como endpoint dessa assinatura.
Por exemplo,
https://myproject.appspot.com/myhandler
.
REST
Para criar uma assinatura de push, use o
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 este exemplo, siga as instruções de configuração do C# na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API C# do Pub/Sub documentação de referência.
Para 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 este exemplo, siga as instruções de configuração do Go na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API Go do Pub/Sub documentação de referência.
Para 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 do Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a API Java do Pub/Sub documentação de referência.
Para 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 do PHP no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a API PHP do Pub/Sub documentação de referência.
Para 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 do Python no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a API Python do Pub/Sub documentação de referência.
Para 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 este exemplo, siga as instruções de configuração do Ruby na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API Ruby do Pub/Sub documentação de referência.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Monitorar assinaturas de push
O Cloud Monitoring fornece várias métricas para monitorar assinaturas.
Para uma lista de todas as métricas disponíveis relacionadas ao Pub/Sub e as descrições deles, consulte Documentação de monitoramento do Pub/Sub.
Também é possível monitorar as assinaturas no Pub/Sub.
A seguir
- Crie ou modifique uma assinatura com os comandos
gcloud
. - Crie ou modifique uma assinatura com as APIs REST.