Este tutorial demonstra como escrever e acionar funções do Cloud Run baseadas em eventos com um acionador do Pub/Sub.
Pode configurar o encaminhamento de eventos, incluindo a origem do evento e o destino do evento, especificando filtros para um acionador do Eventarc. Para o exemplo neste tutorial, a publicação de uma mensagem num tópico do Pub/Sub aciona o evento e é enviado um pedido à sua função sob a forma de um pedido HTTP.
Se está a começar a usar o Pub/Sub e quer saber mais, consulte a documentação do Pub/Sub para inícios rápidos e referências importantes.
Objetivos
Neste tutorial, vai:
Custos
Neste documento, usa os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custos com base na sua utilização projetada,
use a calculadora de preços.
Antes de começar
As restrições de segurança definidas pela sua organização podem impedir a conclusão dos seguintes passos. Para informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
Install the Google Cloud CLI.
-
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Verify that billing is enabled for your Google Cloud project.
-
Install the Google Cloud CLI.
-
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Verify that billing is enabled for your Google Cloud project.
- Se não estiver a usar o Cloud Shell, atualize os componentes da CLI Google Cloud
e inicie sessão com a sua conta:
gcloud components update gcloud auth login
- Ative as APIs:
gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ logging.googleapis.com \ pubsub.googleapis.com
- Defina as variáveis de configuração usadas neste tutorial:
export REGION=us-central1 gcloud config set run/region ${REGION} gcloud config set run/platform managed gcloud config set eventarc/location ${REGION}
- Crie uma conta de serviço:
SERVICE_ACCOUNT=eventarc-trigger-sa gcloud iam service-accounts create $SERVICE_ACCOUNT
Se estiver ao abrigo de uma política da organização de restrição de domínio que restringe as invocações não autenticadas para o seu projeto, tem de aceder ao serviço implementado conforme descrito em Testar serviços privados.
-
Se for o criador do projeto, é-lhe atribuída a função básica de proprietário (
roles/owner
). Por predefinição, esta função do Identity and Access Management (IAM) inclui as autorizações necessárias para acesso total à maioria dos Google Cloud recursos e pode ignorar este passo.Se não for o criador do projeto, as autorizações necessárias têm de ser concedidas no projeto ao principal adequado. Por exemplo, um principal pode ser uma Conta Google (para utilizadores finais) ou uma conta de serviço (para aplicações e cargas de trabalho de computação). Para mais informações, consulte a página Funções e autorizações do destino de eventos.
Para receber as autorizações de que precisa para concluir este tutorial, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:
-
Cloud Run Source Developer (
roles/run.sourceDeveloper
) -
Project IAM Admin (
roles/resourcemanager.projectIamAdmin
) -
Utilizador da conta de serviço (
roles/iam.serviceAccountUser
) -
Administrador de utilização de serviços (
roles/serviceusage.serviceUsageAdmin
) -
Aceder à vista de registos (
roles/logging.viewAccessor
)
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.
Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.
Tenha em atenção que, por predefinição, as autorizações do Cloud Build incluem autorizações para carregar e transferir artefactos do Artifact Registry.
-
Cloud Run Source Developer (
Tome nota da conta de serviço predefinida do Compute Engine, uma vez que a vai anexar a um acionador do Eventarc para representar a identidade do acionador para fins de teste. Esta conta de serviço é criada automaticamente depois de ativar ou usar um Google Cloud serviço que usa o Compute Engine e com o seguinte formato de email:
PROJECT_NUMBER-compute@developer.gserviceaccount.com
Substitua
PROJECT_NUMBER
pelo seu Google Cloud número do projeto. Pode encontrar o número do projeto na página Boas-vindas da Google Cloud consola ou executando o seguinte comando:gcloud projects describe PROJECT_ID --format='value(projectNumber)'
Para ambientes de produção, recomendamos vivamente que crie uma nova conta de serviço e lhe conceda uma ou mais funções do IAM que contenham as autorizações mínimas necessárias e siga o princípio do privilégio mínimo.
- Por predefinição, os serviços do Cloud Run só podem ser chamados por proprietários do projeto, editores do projeto e administradores e invocadores do Cloud Run.
Pode controlar o acesso por serviço. No entanto, para fins de teste, conceda a função de invocador do Cloud Run (
run.invoker
) no Google Cloud projeto à conta de serviço do Compute Engine. Isto concede a função em todos os serviços e tarefas do Cloud Run num projeto.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/run.invoker
Tenha em atenção que, se criar um acionador para um serviço do Cloud Run autenticado sem conceder a função de invocador do Cloud Run, o acionador é criado com êxito e está ativo. No entanto, o acionador não funciona conforme esperado e é apresentada uma mensagem semelhante à seguinte nos registos:
The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
- Conceda a função de
recetor de eventos do Eventarc (
roles/eventarc.eventReceiver
) no projeto à conta de serviço predefinida do Compute Engine para que o acionador do Eventarc possa receber eventos de fornecedores de eventos.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/eventarc.eventReceiver
- Antes de criar um acionador para eventos diretos do Cloud Storage, conceda a função de publicador do Pub/Sub (
roles/pubsub.publisher
) ao agente de serviço do Cloud Storage:SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)" gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:${SERVICE_ACCOUNT}" \ --role='roles/pubsub.publisher'
- Se ativou o agente do serviço Cloud Pub/Sub a 8 de abril de 2021 ou antes, para suportar pedidos de envio do Pub/Sub autenticados, conceda a função de criador de tokens de conta de serviço (
roles/iam.serviceAccountTokenCreator
) ao agente do serviço. Caso contrário, esta função é concedida por predefinição:gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator
Clone o repositório da app de exemplo para a sua máquina local:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Ir
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
.NET
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
PHP
git clone https://github.com/GoogleCloudPlatform/php-docs-samples.git
Altere para o diretório que contém o código de exemplo para aceder ao Pub/Sub:
Node.js
cd nodejs-docs-samples/functions/v2/helloPubSub/
Python
cd python-docs-samples/functions/v2/pubsub/
Ir
cd golang-samples/functions/functionsv2/hellopubsub/
Java
cd java-docs-samples/functions/v2/pubsub/
.NET
cd dotnet-docs-samples/functions/helloworld/HelloPubSub/
Ruby
cd ruby-docs-samples/functions/helloworld/pubsub/
PHP
cd php-docs-samples/functions/helloworld_pubsub/
Veja o exemplo de código:
Node.js
Python
Ir
Java
.NET
Ruby
PHP
- FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
nodejs22
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. - FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
python313
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. - FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
go124
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. - FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
java21
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. - FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
dotnet8
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. - FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
ruby34
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. - FUNCTION com o nome da função que está a implementar. Se omitir este parâmetro, é-lhe pedido que introduza um nome quando executar o comando.
- BASE_IMAGE com o ambiente de imagem base para a sua função,
por exemplo,
php84
. Para mais detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Tempos de execução de idiomas e imagens base suportados. Crie um acionador do Eventarc Pub/Sub:
gcloud eventarc triggers create TRIGGER_NAME \ --location=${REGION} \ --destination-run-service=FUNCTION \ --destination-run-region=${REGION} \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
Substituir:
- TRIGGER_NAME com o nome do acionador.
- FUNCTION com o nome da sua função.
- PROJECT_NUMBER com o seu Google Cloud número do projeto.
Tenha em atenção que, quando cria um acionador do Eventarc pela primeira vez num projeto, pode haver um atraso no aprovisionamento do agente do serviço Eventarc. Google Cloud Normalmente, pode resolver este problema tentando criar o acionador novamente. Para mais informações, consulte o artigo Erros de acesso negado.
Confirme que o acionador foi criado com êxito. Tenha em atenção que, embora o acionador seja criado imediatamente, pode demorar até dois minutos para que um acionador fique totalmente funcional.
gcloud eventarc triggers list --location=${REGION}
O resultado deve ser semelhante ao seguinte:
NAME: helloworld-events TYPE: google.cloud.pubsub.topic.v1.messagePublished DESTINATION: Cloud Run service: helloworld-events ACTIVE: Yes LOCATION: us-central1
Atribua o tópico a uma variável:
TOPIC_ID=$(gcloud eventarc triggers describe TRIGGER_NAME --location $REGION --format='value(transport.pubsub.topic)')
Publicar uma mensagem no tópico:
gcloud pubsub topics publish $TOPIC_ID --message="Hello World"
- Navegue para a Google Cloud consola.
- Clique na função.
Selecione o separador Registos.
Os registos podem demorar alguns momentos a aparecer. Se não os vir imediatamente, verifique novamente após alguns instantes.
Procure a mensagem "Hello World!".
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Elimine o serviço do Cloud Run que implementou neste tutorial:
gcloud run services delete SERVICE_NAME
Onde
SERVICE_NAME
é o nome do serviço escolhido.Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.
Remova todas as configurações predefinidas da CLI gcloud que adicionou durante a configuração do tutorial.
Por exemplo:
gcloud config unset run/region
ou
gcloud config unset project
Elimine outros Google Cloud recursos criados neste tutorial:
- Elimine o acionador do Eventarc:
Substituagcloud eventarc triggers delete TRIGGER_NAME
TRIGGER_NAME
pelo nome do seu acionador.
- Elimine o acionador do Eventarc:
Funções necessárias
O utilizador ou o administrador tem de conceder à conta de implementação, à identidade do acionador e, opcionalmente, ao agente de serviço do Pub/Sub e ao agente de serviço do Cloud Storage as seguintes funções de IAM.
Funções necessárias para a conta do implementador
Funções necessárias para a identidade do acionador
Função opcional para o agente do serviço do Cloud Storage
Função opcional para o agente do serviço Pub/Sub
Crie um tópico do Pub/Sub
No Cloud Run, os tópicos do Pub/Sub não são criados automaticamente quando implementa uma função. Antes de implementar a sua função, publique uma mensagem neste tópico do Pub/Sub para acionar a função:
gcloud pubsub topics create YOUR_TOPIC_NAME
Prepare a aplicação
Implemente uma função orientada por eventos
Para implementar a função, execute o seguinte comando no diretório que contém o código de exemplo:
Node.js
gcloud run deploy FUNCTION \
--source . \
--function helloPubSub \
--base-image BASE_IMAGE \
Substituir:
Python
gcloud run deploy FUNCTION \
--source . \
--function subscribe \
--base-image BASE_IMAGE \
Substituir:
Ir
gcloud run deploy FUNCTION \
--source . \
--function HelloPubSub \
--base-image BASE_IMAGE \
Substituir:
Java
gcloud run deploy FUNCTION \
--source . \
--function functions.SubscribeToTopic \
--base-image BASE_IMAGE \
Substituir:
.NET
gcloud run deploy FUNCTION \
--source . \
--function HelloPubSub.Function \
--base-image BASE_IMAGE \
Substituir:
Ruby
gcloud run deploy FUNCTION \
--source . \
--function hello_pubsub \
--base-image BASE_IMAGE \
Substituir:
PHP
gcloud run deploy FUNCTION \
--source . \
--function helloworldPubsub \
--base-image BASE_IMAGE \
Substituir:
Se lhe for pedido que crie um repositório na região especificada, responda
premindo y
.
Quando a implementação estiver concluída, a CLI Google Cloud apresenta um URL onde o serviço está em execução.
Crie um acionador do Eventarc
Para implementar a função com um acionador do Pub/Sub, execute o seguinte comando no diretório que contém o código de exemplo:
Acionar a função
Para testar a função Pub/Sub:
O serviço do Cloud Run regista o corpo da mensagem recebida. Pode ver esta opção na secção Registos da sua instância do Cloud Run:
Limpar
Se criou um novo projeto para este tutorial, elimine o projeto. Se usou um projeto existente e quer mantê-lo sem as alterações adicionadas neste tutorial, elimine os recursos criados para o tutorial.
Elimine o projeto
A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.
Para eliminar o projeto: