Neste documento, descrevemos como criar uma assinatura por push. É possível usar o consoleCloud de Confiance , a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub para criar uma assinatura por push.
Antes de começar
- Saiba mais sobre assinaturas.
- Entender como as assinaturas por push funcionam.
Papéis e permissões necessárias
Para receber as permissões necessárias
para criar uma assinatura por 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 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 uma assinatura por push. Para acessar 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 uma assinatura por push:
-
pubsub.subscriptions.createno projeto -
pubsub.topics.attachSubscriptionno assunto
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Assinaturas entre projetos
Se você criar uma assinatura em um projeto para um tópico em outro, será necessário ter a permissão pubsub.subscriptions.create no projeto em que a assinatura está sendo criada e a permissão pubsub.topics.attachSubscription no tópico.
Propriedades de assinatura por push
As assinaturas por push são compatíveis com todas as propriedades comuns de assinatura. As seções a seguir descrevem propriedades específicas das assinaturas por push.
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 Pub/Sub entrega mensagens para endpoints push da mesma região Cloud de Confiance em que o serviço Pub/Sub armazena as mensagens. O serviço Pub/Sub entrega mensagens da mesma região Cloud de Confiance com base no melhor esforço.
Se os assinantes usam um firewall, eles não podem receber solicitações push. Para receber solicitações push, desative o firewall e verifique o JSON Web Token (JWT) usado na solicitação. Se um assinante tiver um firewall, talvez você receba um erro
403 permission denied.O Pub/Sub não exige comprovação de propriedade para domínios do URL de assinatura push. Se o domínio receber solicitações POST inesperadas do Pub/Sub, denuncie suspeitas de abuso.
Autenticação
Ativar a autenticação. Quando ativada, as mensagens entregues pelo Pub/Sub ao endpoint de push incluem um cabeçalho de autorização para permitir que o endpoint autentique a solicitação. Mecanismos automáticos de autenticação e autorização estão disponíveis para endpoints do App Engine Standard e do Cloud Run functions hospedados no mesmo projeto da assinatura.
A configuração de autenticação de uma assinatura por push autenticada consiste em uma conta serviço gerenciado pelo usuário e nos parâmetros de público-alvo especificados em uma chamada create, patch ou ModifyPushConfig. Você também precisa conceder um papel específico a uma conta de serviço, conforme discutido na próxima seção.
Público-alvo. Uma única string que não diferencia maiúsculas de minúsculas que o webhook usa para validar o público-alvo pretendido deste token específico.
Conta de serviço. O Pub/Sub cria automaticamente uma conta de serviço para você no formato
service-{PROJECT_NUMBER}@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com.
Pré-requisitos para ativar a autenticação
A conta serviço gerenciado pelo usuário é a conta de serviço associada à assinatura por push. Essa conta é usada como a declaração email do JSON Web Token (JWT) gerado. Veja a seguir uma lista de requisitos para
a conta de serviço:
Essa conta serviço gerenciado pelo usuário precisa estar no mesmo projeto que a assinatura por push.
O principal que está criando ou modificando a assinatura por push precisa ter a permissão
iam.serviceAccounts.actAsna conta de serviço gerenciada pelo usuário para anexar a conta de serviço à assinatura por push. Para mais informações, consulte Anexar contas de serviço a recursos.Permissões necessárias: 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 que a conta de serviço especificada autentique solicitações push.
Desencapsulamento de payload
A opção Ativar desencapsulamento de payload remove todos os metadados das mensagens do Pub/Sub, exceto os dados da mensagem. Com o desencapsulamento de payload, os dados da mensagem são entregues diretamente como o corpo HTTP.
Você também pode ativar a opção Gravar metadados. A opção Gravar metadados adiciona os metadados removidos das mensagens ao cabeçalho da solicitação.
Entregar em endereços VPC particulares
O Pub/Sub opera fora das redes VPC e não pode enviar mensagens diretamente para endereços VPC particulares. No entanto, é possível usar o Eventarc para rotear mensagens para serviços na VPC. O Pub/Sub pode enviar mensagens para um gatilho do Eventarc, que pode encaminhá-las para um serviço na sua VPC, como um serviço do Cloud Run ou uma execução do Workflows. Para mais informações, consulte a documentação do Eventarc.
VPC Service Controls
Para um projeto protegido pelo VPC Service Controls, observe as seguintes limitações para assinaturas por push:
Só é possível criar assinaturas por push em que o endpoint de push está definido como um serviço do Cloud Run com um URL
run.apppadrão ou uma execução do Workflows. Domínios personalizados não funcionam.Ao rotear eventos pelo Eventarc para destinos do Workflows em que o endpoint de push está definido como uma execução do Workflows, só é possível criar assinaturas por push pelo Eventarc.
Não é possível atualizar as assinaturas por push atuais. Essas assinaturas por push continuam funcionando, mas não são protegidas pelo VPC Service Controls.
Criar uma assinatura por 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, como mostrado nos exemplos a seguir.
Console
Para criar uma assinatura por push, siga estas etapas:
No console do Cloud de Confiance , acesse a página Assinaturas.
Clique em Criar assinatura.
No campo ID da assinatura, insira um nome.
Para ver informações sobre como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
Na lista Tópico do Pub/Sub, selecione um tópico para a assinatura ler.
Em Tipo de entrega, selecione Push.
No campo Endpoint URL, insira o URL do endpoint.
Opcional: para ativar a autenticação, siga estas etapas:
- Selecione Ativar autenticação.
- Na lista Conta de serviço, selecione a conta de serviço para realizar a autenticação.
- Opcional: no campo Público-alvo, insira um público-alvo.
Para mais informações, consulte Autenticação para assinaturas por push.
Opcional: para ativar o desencapsulamento de payload, selecione Ativar o desencapsulamento de payload.
Para preservar os metadados da mensagem no cabeçalho da solicitação, selecione também Gravar metadados. Essa opção também define um cabeçalho
Content-Typepara suas mensagens.Opcional: na seção Transformações, adicione uma ou mais transformações de mensagem única (SMTs, na sigla em inglês). Para mais informações, consulte Criar uma assinatura com SMTs.
Opcional: no campo Filtro, insira uma expressão de filtro para filtrar mensagens da assinatura. Para mais informações, consulte Filtrar mensagens de uma assinatura.
Em Política de novas tentativas, selecione uma opção. Para mais informações, consulte Política de novas tentativas de assinatura.
Opcional: ative um tópico de mensagens inativas para receber mensagens não entregues.
Marque a caixa de seleção Mensagem morta.
Na lista Tópico de dead-letter, selecione ou crie o tópico de dead-letter.
No campo Máximo de tentativas de entrega, insira o número máximo de tentativas de entrega.
Opcional: na seção Propriedades de exibição, ative ou desative as seguintes opções de exibição:
Opcional: na seção Prazo de confirmação, defina o prazo para o assinante processar e confirmar as mensagens. Para mais informações, consulte Estender o tempo de confirmação com o gerenciamento de locação.
Opcional: na seção Opções de ciclo de vida, configure por quanto tempo a assinatura vai reter mensagens.
Na seção Período de retenção de mensagens, especifique por quanto tempo as mensagens não confirmadas serão retidas.
Para reter mensagens confirmadas e não confirmadas, marque a caixa de seleção Reter mensagens confirmadas.
Para mais informações, consulte Configurar a retenção de mensagens para uma assinatura.
Opcional: em Período de validade, selecione uma opção:
Para definir a expiração da assinatura, marque a caixa de seleção Expirar após este número de dias de inatividade. Insira o número de dias que a assinatura pode ficar inativa antes de o Pub/Sub excluí-la.
Para desativar a expiração da assinatura, marque a caixa de seleção Nunca expirar.
Para mais informações, consulte Expiração da assinatura.
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 Cloud de Confiance , 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.
Na página Adicionar assinatura ao tópico, conclua as etapas descritas no procedimento anterior. O ID do tópico é preenchido automaticamente.
gcloud
-
No console do Cloud de Confiance , ative o Cloud Shell.
Na parte de baixo do console Cloud de Confiance , 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 por 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 sua nova assinatura por push.TOPIC_ID: o nome ou ID do tópico.- PUSH_ENDPOINT: o URL a ser usado como endpoint para esta assinatura.
Por exemplo,
https://myproject.appspot.com/myhandler.
REST
Para criar uma assinatura por 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 para 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 para C#.
Go
O exemplo a seguir usa a versão principal da biblioteca de cliente do Pub/Sub para Go (v2). Se você ainda estiver usando 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 testar esta amostra, siga as instruções de configuração do Go no 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 para Java (em inglês).
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 para Node.js (em inglês).
Node.ts
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 para Node.js (em inglês).
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP 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 para PHP.
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 para Python.
Ruby
O exemplo a seguir usa a biblioteca de cliente do Ruby Pub/Sub v3. Se você ainda estiver usando a biblioteca v2, consulte o guia de migração para a v3. Para conferir uma lista de exemplos de código do Ruby v2, consulte os exemplos de código descontinuados.
Antes de testar esta amostra, siga as instruções de configuração do Ruby no 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.
Monitorar assinaturas por push
O Cloud Monitoring oferece várias métricas para monitorar assinaturas.
Para ver uma lista de todas as métricas disponíveis relacionadas ao Pub/Sub e as descrições delas, consulte a documentação do Monitoring para o Pub/Sub.
Também é possível monitorar assinaturas no Pub/Sub.
A seguir
- Crie ou modifique uma assinatura com comandos
gcloud. - Crie ou modifique uma assinatura com APIs REST.