Acione funções a partir do Cloud Storage com o Eventarc

---

Este tutorial mostra como implementar uma função orientada por eventos no Cloud Run e usar o Eventarc para acionar a função em resposta a eventos do Cloud Storage através da CLI Google Cloud.

Ao especificar filtros para um acionador do Eventarc, pode configurar o encaminhamento de eventos, incluindo a origem do evento e o destino do evento. Para o exemplo neste tutorial, uma atualização a um contentor do Cloud Storage aciona o evento e é enviado um pedido para a sua função sob a forma de um pedido HTTP.

Objetivos

Neste tutorial, vai:

1. Crie um contentor do Cloud Storage para ser a origem do evento.
2. Implemente uma função orientada por eventos.
3. Crie um acionador do Eventarc.
4. Acione a função carregando um ficheiro para o Cloud Storage.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Storage
• Eventarc

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

1. 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

2. Ative as APIs:

   gcloud services enable artifactregistry.googleapis.com \
       cloudbuild.googleapis.com \
       eventarc.googleapis.com \
       run.googleapis.com \
       storage.googleapis.com

3. Defina as variáveis de configuração a usar neste tutorial:

   export REGION=us-central1
   gcloud config set run/region ${REGION}
   gcloud config set run/platform managed
   gcloud config set eventarc/location ${REGION}

4. 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.

Defina 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

1. 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:

   • Editor do Cloud Build (roles/cloudbuild.builds.editor)
   • Administrador do Cloud Run (roles/run.admin)
   • Cloud Run Source Developer (roles/run.sourceDeveloper)
   • Eventarc Admin (roles/eventarc.admin)
   • Aceder à vista de registos (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
   • Utilizador da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin)
   • Administrador de armazenamento (roles/storage.admin)

   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.

Funções necessárias para a identidade do acionador

1. 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:

   [e-mail]

   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.

   Nota:

   A iam.automaticIamGrantsForDefaultServiceAccounts restrição da política da organização impede que a função de editor seja concedida automaticamente às contas de serviço predefinidas. Se tiver criado a sua organização após 3 de maio de 2024, esta restrição é aplicada por predefinição.

   Recomendamos vivamente que aplique esta restrição para desativar a concessão automática de funções. Se desativar a concessão automática de funções, tem de decidir que funções conceder às contas de serviço predefinidas e, em seguida, conceder estas funções manualmente.

   Se a conta de serviço predefinida já tiver a função de editor, recomendamos que substitua a função de editor por funções menos permissivas.Para modificar as funções da conta de serviço em segurança, use o Simulador de políticas para ver o impacto da alteração e, em seguida, conceda e revogue as funções adequadas.

2. 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:[e-mail] \
       --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.
3. 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:[e-mail] \
       --role=roles/eventarc.eventReceiver

Função opcional para o agente do serviço do Cloud Storage

• 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'

Função opcional para o agente do serviço Pub/Sub

• 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:[e-mail] \
      --role=roles/iam.serviceAccountTokenCreator

Crie um contentor do Cloud Storage

Crie um contentor do Cloud Storage para usar como origem de eventos:

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

Nota: o contentor do Cloud Storage tem de estar no mesmo Google Cloud projeto e região ou multirregião que o acionador do Eventarc.

Escreva uma função orientada por eventos

Para escrever uma função orientada por eventos, siga estes passos:

Node.js

1. Crie um novo diretório com o nome helloGCS e mude o diretório para este:

      mkdir helloGCS
      cd helloGCS
   

2. Crie um ficheiro package.json no diretório helloGCS para especificar as dependências do Node.js:

   {
     "name": "nodejs-docs-samples-functions-v2-storage",
     "version": "0.0.1",
     "private": true,
     "license": "Apache-2.0",
     "author": "Google LLC",
     "repository": {
       "type": "git",
       "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
     },
     "engines": {
       "node": ">=16.0.0"
     },
     "scripts": {
       "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
     },
     "dependencies": {
       "@google-cloud/functions-framework": "^3.0.0"
     },
     "devDependencies": {
       "c8": "^10.0.0",
       "mocha": "^10.0.0",
       "sinon": "^18.0.0",
       "supertest": "^7.0.0"
     }
   }
   

3. Crie um ficheiro index.js no diretório helloGCS com o seguinte exemplo de Node.js:

   const functions = require('@google-cloud/functions-framework');
   
   // Register a CloudEvent callback with the Functions Framework that will
   // be triggered by Cloud Storage.
   functions.cloudEvent('helloGCS', cloudEvent => {
     console.log(`Event ID: ${cloudEvent.id}`);
     console.log(`Event Type: ${cloudEvent.type}`);
   
     const file = cloudEvent.data;
     console.log(`Bucket: ${file.bucket}`);
     console.log(`File: ${file.name}`);
     console.log(`Metageneration: ${file.metageneration}`);
     console.log(`Created: ${file.timeCreated}`);
     console.log(`Updated: ${file.updated}`);
   });

Python

1. Crie um novo diretório com o nome helloGCS e mude o diretório para este:

      mkdir helloGCS
      cd helloGCS
   

2. Crie um ficheiro requirements.txt no diretório helloGCS para especificar as dependências do Python:

   functions-framework==3.8.2
   cloudevents==1.11.0

   Isto adiciona os pacotes necessários para a amostra.

3. Crie um ficheiro main.py no diretório helloGCS com o seguinte exemplo de Python:

   from cloudevents.http import CloudEvent
   
   import functions_framework
   
   
   # Triggered by a change in a storage bucket
   @functions_framework.cloud_event
   def hello_gcs(cloud_event: CloudEvent) -> tuple:
       """This function is triggered by a change in a storage bucket.
   
       Args:
           cloud_event: The CloudEvent that triggered this function.
       Returns:
           The event ID, event type, bucket, name, metageneration, and timeCreated.
       """
       data = cloud_event.data
   
       event_id = cloud_event["id"]
       event_type = cloud_event["type"]
   
       bucket = data["bucket"]
       name = data["name"]
       metageneration = data["metageneration"]
       timeCreated = data["timeCreated"]
       updated = data["updated"]
   
       print(f"Event ID: {event_id}")
       print(f"Event type: {event_type}")
       print(f"Bucket: {bucket}")
       print(f"File: {name}")
       print(f"Metageneration: {metageneration}")
       print(f"Created: {timeCreated}")
       print(f"Updated: {updated}")
   
       return event_id, event_type, bucket, name, metageneration, timeCreated, updated
   
   

Implemente uma função orientada por eventos

Implemente a função com o nome helloworld-events executando o seguinte comando no diretório que contém o código de exemplo:

Node.js

gcloud run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

Substitua BASE_IMAGE pelo ambiente de imagem base da 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.

Python

gcloud run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image BASE_IMAGE \
      --region us-central1

Substitua BASE_IMAGE pelo ambiente de imagem base da 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.

Quando a implementação estiver concluída, a CLI Google Cloud apresenta um URL onde o seu serviço está em execução.

Crie um acionador do Eventarc

O acionador do Eventarc envia eventos do contentor do Cloud Storage para o seu serviço do helloworld-eventsCloud Run.

1. Crie um acionador que filtre eventos do Cloud Storage:

   gcloud eventarc triggers create TRIGGER_NAME  \
       --location=${REGION} \
       --destination-run-service=helloworld-events  \
       --destination-run-region=${REGION} \
       --event-filters="type=google.cloud.storage.object.v1.finalized" \
       --event-filters="bucket=PROJECT_ID-bucket" \
       --service-account=[e-mail]

   Substituir:

   • TRIGGER_NAME com o nome do acionador.
   • PROJECT_ID com o seu Google Cloud ID do projeto.
   • 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.

2. 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.storage.object.v1.finalized
   DESTINATION: Cloud Run service: helloworld-events
   ACTIVE: Yes
   LOCATION: us-central1
   

Gere e veja um evento

Carregue um ficheiro de texto para o contentor do Cloud Storage para gerar um evento que é encaminhado para a função. A função do Cloud Run regista o evento nos registos do serviço.

1. Carregue um ficheiro de texto para o Cloud Storage para gerar um evento:

    echo "Hello World" > random.txt
    gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
   

   O carregamento gera um evento e a função do Cloud Run regista a mensagem do evento.

2. Para ver a entrada do registo:

   1. Filtre as entradas do registo e devolva o resultado no formato JSON:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      

   2. Procure uma entrada de registo semelhante a:

      [
        {
         ....
          "resource": {
            "labels": {
              ....
              "location": "us-central1",
              .....
              "service_name": "helloworld-events"
            },
          },
          "textPayload": "File: random.txt",
           .....
        }
      ]
      

      Nota: se não vir uma entrada de registo, aguarde alguns minutos e tente novamente o comando gcloud logging read. O acionador pode demorar até dois minutos após a criação a começar a filtrar eventos.

      Os registos podem demorar alguns momentos a aparecer. Se não os vir imediatamente, verifique novamente após um minuto.

Depois de ver a entrada do registo, isto confirma que implementou com êxito uma função orientada por eventos que foi acionada quando um ficheiro de texto foi carregado para o Cloud Storage.

Êxito: implementou uma função orientada por eventos no Cloud Run e usou o Eventarc para acionar a função em resposta a eventos do Cloud Storage.

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:

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimine recursos de tutoriais

1. 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.

2. 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

3. Elimine outros Google Cloud recursos criados neste tutorial:

   • Elimine o acionador do Eventarc:

     gcloud eventarc triggers delete TRIGGER_NAME
     

     Substitua TRIGGER_NAME pelo nome do seu acionador.

O que se segue?

• Crie acionadores do Eventarc para outros tipos de eventos
• Faça a gestão das funções