Este tutorial simples demonstra como escrever, implementar e acionar uma função do Cloud Run baseada em eventos com um acionador do Cloud Storage para responder a eventos do Cloud Storage.
Se procura exemplos de código para usar o Cloud Storage, aceda ao navegador de exemplos do Google Cloud.
Objetivos
- Escrever e implementar uma função do Cloud Run baseada em eventos.
- Acione a função carregando um ficheiro para o Cloud Storage.
Custos
Neste documento, usa os seguintes componentes faturáveis do Google Cloud:
- Cloud Run functions
- Cloud Storage
Para gerar uma estimativa de custos com base na sua utilização projetada,
use a calculadora de preços.
Antes de começar
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, Cloud Storage, and Eventarc APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Install the Google Cloud CLI.
-
Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, Cloud Storage, and Eventarc APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Install the Google Cloud CLI.
-
Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
- Prepare o ambiente de programação:
Crie um contentor do Cloud Storage para carregar um ficheiro de teste, onde
YOUR_TRIGGER_BUCKET_NAME
é um nome de contentor exclusivo a nível global:gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME
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
Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.
Altere para o diretório que contém o código de exemplo das funções do Cloud Run:
Node.js
cd nodejs-docs-samples/functions/helloworld/
Python
cd python-docs-samples/functions/helloworld/
Go
cd golang-samples/functions/helloworld/
Java
cd java-docs-samples/functions/helloworld/hello-gcs/
Ruby
cd ruby-docs-samples/functions/helloworld/storage/
Crie um ficheiro
gcf-test.txt
vazio no diretório onde se encontra o código de exemplo.Carregue o ficheiro para o Cloud Storage para acionar a função:
gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
onde
YOUR_TRIGGER_BUCKET_NAME
é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste.Verifique os registos para se certificar de que as execuções foram concluídas:
gcloud functions logs read --limit 50
Crie um ficheiro
gcf-test.txt
vazio no diretório onde se encontra o código de exemplo.Certifique-se de que o seu contentor não tem controlo de versões:
gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning
Carregue o ficheiro para o Cloud Storage:
gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
onde
YOUR_TRIGGER_BUCKET_NAME
é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste. Neste ponto, a função ainda não deve ser executada.Elimine o ficheiro para acionar a função:
gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
Verifique os registos para se certificar de que as execuções foram concluídas:
gcloud functions logs read --limit 50
Crie um ficheiro
gcf-test.txt
vazio no diretório onde se encontra o código de exemplo.Certifique-se de que o seu contentor tem a gestão de versões ativada:
gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --versioning
Carregue o ficheiro para o Cloud Storage:
gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
onde
YOUR_TRIGGER_BUCKET_NAME
é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste. Neste ponto, a função ainda não deve ser executada.Arquive o ficheiro para acionar a função:
gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt
Monitorize os registos para se certificar de que as execuções foram concluídas:
gcloud functions logs read --limit 50
Crie um ficheiro
gcf-test.txt
vazio no diretório onde se encontra o código de exemplo.Certifique-se de que o seu contentor não tem controlo de versões:
gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning
Carregue o ficheiro para o Cloud Storage:
gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
onde
YOUR_TRIGGER_BUCKET_NAME
é o nome do seu contentor do Cloud Storage onde vai carregar um ficheiro de teste. Neste ponto, a função ainda não deve ser executada.Atualize os metadados do ficheiro:
gcloud storage objects update gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt --content-type=text/plain
Monitorize os registos para se certificar de que as execuções foram concluídas:
gcloud functions logs read --limit 50
- 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.
Se já tiver a CLI gcloud instalada, atualize-a executando o seguinte comando:
gcloud components update
A preparar a aplicação
Implementar e acionar a função
As funções do Cloud Storage baseiam-se em notificações do Pub/Sub do Cloud Storage e suportam tipos de eventos semelhantes:
As secções seguintes descrevem como implementar e acionar uma função para cada um destes tipos de eventos.
Objeto finalizado
Os eventos de finalização de objetos são acionados quando uma "escrita" de um objeto do Cloud Storage é finalizada com êxito. Em particular, isto significa que a criação de um novo objeto ou a substituição de um objeto existente aciona este evento. As operações de arquivo e atualização de metadados são ignoradas por este acionador.
Object Finalize: implementar a função
Veja a função de exemplo, que processa eventos do Cloud Storage:
Node.js
Python
Go
Java
Ruby
Para implementar a função, execute o seguinte comando no diretório onde o código de exemplo está localizado:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão suportada do Node.js para executar
a sua função.
Python
gcloud functions deploy hello_gcs \ --runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Python suportada para executar
a sua função.
Go
gcloud functions deploy HelloGCS \ --runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Go suportada para executar
a sua função.
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java17 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão Java suportada para executar
a sua função.
Ruby
gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Ruby suportada para executar
a sua função.
em que YOUR_TRIGGER_BUCKET_NAME
é o nome do contentor do Cloud Storage que aciona a função.
Object Finalize: acionar a função
Para acionar a função:
Eliminação de objeto
Os eventos de eliminação de objetos são acionados quando um objeto é eliminado temporariamente. Isto acontece quando um objeto é substituído ou eliminado num contentor sem a versão de objetos ativada. A eliminação de um objeto especificando o respetivo número de geração também resulta na eliminação temporária do objeto.
Eliminação de objetos: implementação da função
Usando o mesmo exemplo de código que no exemplo de finalização, implemente a função com a eliminação de objetos como evento acionador. Execute o seguinte comando no diretório onde o exemplo de código está localizado:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão suportada do Node.js para executar
a sua função.
Python
gcloud functions deploy hello_gcs \ --runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Python suportada para executar
a sua função.
Go
gcloud functions deploy HelloGCS \ --runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Go suportada para executar
a sua função.
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java17 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão Java suportada para executar
a sua função.
Ruby
gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Ruby suportada para executar
a sua função.
em que YOUR_TRIGGER_BUCKET_NAME
é o nome do contentor do Cloud Storage que aciona a função.
Eliminação de objetos: acionamento da função
Para acionar a função:
Tenha em atenção que a função pode demorar algum tempo a terminar a execução.
Arquivo de objetos
Os eventos de arquivo de objetos são acionados quando uma versão ativa de um objeto se torna uma versão não atual. Isto acontece quando um objeto é substituído ou eliminado num contentor com a versão de objetos ativada.
Arquivo de objetos: implementar a função
Usando o mesmo exemplo de código que no exemplo de finalização, implemente a função com o arquivo de objetos como o evento de acionador. Execute o seguinte comando no diretório onde o exemplo de código está localizado:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão suportada do Node.js para executar
a sua função.
Python
gcloud functions deploy hello_gcs \ --runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Python suportada para executar
a sua função.
Go
gcloud functions deploy HelloGCS \ --runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Go suportada para executar
a sua função.
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java17 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão Java suportada para executar
a sua função.
Ruby
gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Ruby suportada para executar
a sua função.
em que YOUR_TRIGGER_BUCKET_NAME
é o nome do contentor do Cloud Storage que aciona a função.
Arquivo de objetos: acionar a função
Para acionar a função:
Atualização dos metadados do objeto
Os eventos de atualização de metadados são acionados quando os metadados do objeto existente são atualizados.
Atualização dos metadados do objeto: implementação da função
Usando o mesmo exemplo de código que no exemplo de finalização, implemente a função com a atualização de metadados como o evento de acionamento. Execute o seguinte comando no diretório onde o exemplo de código está localizado:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão suportada do Node.js para executar
a sua função.
Python
gcloud functions deploy hello_gcs \ --runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Python suportada para executar
a sua função.
Go
gcloud functions deploy HelloGCS \ --runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Go suportada para executar
a sua função.
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java17 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão Java suportada para executar
a sua função.
Ruby
gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
Use a flag --runtime
para especificar o ID de tempo de execução de uma
versão do Ruby suportada para executar
a sua função.
em que YOUR_TRIGGER_BUCKET_NAME
é o nome do contentor do Cloud Storage que aciona a função.
Atualização de metadados de objetos: acionar a função
Para acionar a função:
Limpar
Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.
Eliminar o projeto
A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.
Para eliminar o projeto:
A eliminar a função
A eliminação de funções do Cloud Run não remove recursos armazenados no Cloud Storage.
Para eliminar a função que criou neste tutorial, execute o seguinte comando:
Node.js
gcloud functions delete helloGCS
Python
gcloud functions delete hello_gcs
Go
gcloud functions delete HelloGCS
Java
gcloud functions delete java-gcs-function
Ruby
gcloud functions delete hello_gcs
Também pode eliminar funções do Cloud Run a partir da Google Cloud consola.