Neste tutorial básico, demonstraremos como escrever, implantar e acionar uma função do Cloud orientada a eventos com um gatilho do Cloud Storage para responder a eventos do Cloud Storage.
Acesse o navegador de amostra do Google Cloud se você estiver em busca de exemplos de código para usar o Cloud Storage.
Objetivos
- Escrever e implantar uma função do Cloud orientada a eventos.
- Acionar a função fazendo upload de um arquivo no Cloud Storage.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
- Cloud Functions
- Cloud Build
- Pub/Sub
- Cloud Storage
- Artifact Registry
- Eventarc
- Cloud Logging
For details, see Cloud Functions pricing.
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:
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.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Enable the Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, and Pub/Sub APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Enable the Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, and Pub/Sub APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Prepare seu ambiente de desenvolvimento:
Node.js
Python
Go
Java
C#
Ruby
PHP
Se a gcloud CLI já estiver instalada, atualize-a executando o seguinte comando:
gcloud components update
Prerequisites
Crie um bucket regional, em que
YOUR_BUCKET_NAME
é um nome de bucket globalmente exclusivo eREGION
é a região em que você planeja implantar a função:gsutil mb -l REGION gs://YOUR_BUCKET_NAME
Para usar as funções do Cloud Storage, conceda a função
pubsub.publisher
à conta de serviço do Cloud Storage:PROJECT_ID=$(gcloud config get-value project) PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)') SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER) gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SERVICE_ACCOUNT \ --role roles/pubsub.publisher
Preparar o aplicativo
Clone o repositório do app de amostra na máquina local:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
C#
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
PHP
git clone https://github.com/GoogleCloudPlatform/php-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Altere para o diretório que contém o código de amostra do Cloud Functions:
Node.js
cd nodejs-docs-samples/functions/v2/helloGCS/
Python
cd python-docs-samples/functions/v2/storage/
Go
cd golang-samples/functions/functionsv2/hellostorage/
Java
cd java-docs-samples/functions/v2/hello-gcs/
C#
cd dotnet-docs-samples/functions/helloworld/HelloGcs/
Ruby
cd ruby-docs-samples/functions/helloworld/storage/
PHP
cd php-docs-samples/functions/helloworld_storage/
Implantar e acionar a função
Atualmente, as funções do Cloud Storage são baseadas em notificações de Pub/Sub do Cloud Storage e são compatíveis com tipos de eventos semelhantes:
As seções a seguir descrevem como implantar e acionar uma função para cada um desses tipos de eventos.
Finalização do objeto
Os eventos de finalização de objeto são acionados quando um "write" (escrever) de um objeto do Cloud Storage é finalizado com sucesso. Especificamente, isso significa que criar um novo objeto ou substituir um objeto existente aciona esse evento. As operações de atualização de metadados e arquivamento são ignoradas por esse gatilho.
Finalizar o objeto: implantar a função
Confira a amostra da função, que processa os eventos do Cloud Storage:
Node.js
Python
Go
Java
C#
Ruby
PHP
Para implantar a função, execute o seguinte comando no diretório em que o código de amostra está localizado:
Node.js
gcloud functions deploy nodejs-finalize-function \ --gen2 \ --runtime=nodejs20 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.
Python
gcloud functions deploy python-finalize-function \ --gen2 \ --runtime=python312 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.
Go
gcloud functions deploy go-finalize-function \ --gen2 \ --runtime=go121 \ --region=REGION
\ --source=. \ --entry-point=HelloStorage \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.
Java
gcloud functions deploy java-finalize-function \ --gen2 \ --runtime=java17 \ --region=REGION
\ --source=. \ --entry-point=functions.HelloGcs \ --memory=512MB \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.
C#
gcloud functions deploy csharp-finalize-function \ --gen2 \ --runtime=dotnet6 \ --region=REGION
\ --source=. \ --entry-point=HelloGcs.Function \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do .NET compatível a fim de executar a função.
Ruby
gcloud functions deploy ruby-finalize-function \ --gen2 \ --runtime=ruby32 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.
PHP
gcloud functions deploy php-finalize-function \ --gen2 \ --runtime=php82 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma
versão do PHP compatível a fim de executar
a função.
Substitua:
- REGION: o nome da
região do Google Cloud em que você quer implantar sua função
(por exemplo,
us-west1
). - YOUR_BUCKET_NAME: o nome do bucket do Cloud Storage que
aciona a função. Ao implantar funções de 2a geração, especifique apenas o nome do bucket,
sem o
gs://
principal. por exemplo,--trigger-event-filters="bucket=my-bucket"
.
Finalização do objeto: acionar a função
Testar a função fazendo upload de um arquivo para seu bucket:
echo "Hello World" > test-finalize.txt gsutil cp test-finalize.txt gs://YOUR_BUCKET_NAME/test-finalize.txt
Você verá o CloudEvent recebido nos registros:
gcloud functions logs read YOUR_FUNCTION_NAME --region REGION --gen2 --limit=10
Exclusão do objeto
Os eventos de exclusão de objetos são mais úteis para buckets sem controle de versão. Eles são acionados quando uma versão antiga de um objeto é excluída. Além disso, eles são acionados quando um objeto é sobrescrito. Os acionadores de exclusão de objetos também podem ser usados com os buckets de controle de versão, acionados quando uma versão de um objeto é excluída permanentemente.
Exclusão do objeto: implantar a função
Usando o mesmo código de amostra do exemplo final, implante a função com exclusão de objetos como o evento gatilho. Execute o seguinte comando no diretório em que o código de amostra está localizado:
Node.js
gcloud functions deploy nodejs-delete-function \ --gen2 \ --runtime=nodejs20 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.
Python
gcloud functions deploy python-delete-function \ --gen2 \ --runtime=python312 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.
Go
gcloud functions deploy go-delete-function \ --gen2 \ --runtime=go121 \ --region=REGION
\ --source=. \ --entry-point=HelloStorage \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.
Java
gcloud functions deploy java-delete-function \ --gen2 \ --runtime=java17 \ --region=REGION
\ --source=. \ --entry-point=functions.HelloGcs \ --memory=512MB \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.
C#
gcloud functions deploy csharp-delete-function \ --gen2 \ --runtime=dotnet6 \ --region=REGION
\ --source=. \ --entry-point=HelloGcs.Function \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do .NET compatível a fim de executar a função.
Ruby
gcloud functions deploy ruby-delete-function \ --gen2 \ --runtime=ruby32 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.
PHP
gcloud functions deploy php-delete-function \ --gen2 \ --runtime=php82 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma
versão do PHP compatível a fim de executar
a função.
Substitua:
- REGION: o nome da
região do Google Cloud em que você quer implantar sua função
(por exemplo,
us-west1
). - YOUR_BUCKET_NAME: o nome do bucket do Cloud Storage que
aciona a função. Ao implantar funções de 2a geração, especifique apenas o nome do bucket,
sem o
gs://
principal. por exemplo,--trigger-event-filters="bucket=my-bucket"
.
Exclusão do objeto: acionar a função
Para acionar a função:
Crie um arquivo vazio
test-delete.txt
no diretório em que o código de amostra está localizado.Verifique se o bucket não tem controle de versão:
gsutil versioning set off gs://YOUR_BUCKET_NAME
Faça upload do arquivo no Cloud Storage:
gsutil cp test-delete.txt gs://YOUR_BUCKET_NAME
em que
YOUR_BUCKET_NAME
é o nome do bucket do Cloud Storage onde será feito o upload de um arquivo de teste. Neste momento, a função ainda não é executada.Exclua o arquivo para acionar a função:
gsutil rm gs://YOUR_BUCKET_NAME/test-delete.txt
Você verá o CloudEvent recebido nos registros:
gcloud functions logs read YOUR_FUNCTION_NAME --region REGION --gen2 --limit=10
Observe que a execução da função pode levar algum tempo para ser concluída.
Arquivamento do objeto
Os eventos de arquivamento de objeto podem ser usados apenas com buckets de controle de versão. Eles são acionados quando uma versão anterior de um objeto é arquivada. Especificamente, isso significa que, quando um objeto é sobrescrito ou excluído, um evento de arquivamento é acionado.
Arquivamento do objeto: implante a função
Usando o mesmo código de amostra do exemplo final, implante a função com arquivamento de objetos como o evento gatilho. Execute o seguinte comando no diretório em que o código de amostra está localizado:
Node.js
gcloud functions deploy nodejs-archive-function \ --gen2 \ --runtime=nodejs20 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.
Python
gcloud functions deploy python-archive-function \ --gen2 \ --runtime=python312 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.
Go
gcloud functions deploy go-archive-function \ --gen2 \ --runtime=go121 \ --region=REGION
\ --source=. \ --entry-point=HelloStorage \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.
Java
gcloud functions deploy java-archive-function \ --gen2 \ --runtime=java17 \ --region=REGION
\ --source=. \ --entry-point=functions.HelloGcs \ --memory=512MB \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.
C#
gcloud functions deploy csharp-archive-function \ --gen2 \ --runtime=dotnet6 \ --region=REGION
\ --source=. \ --entry-point=HelloGcs.Function \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do .NET compatível a fim de executar a função.
Ruby
gcloud functions deploy ruby-archive-function \ --gen2 \ --runtime=ruby32 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.
PHP
gcloud functions deploy php-archive-function \ --gen2 \ --runtime=php82 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.archived" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma
versão do PHP compatível a fim de executar
a função.
Substitua:
- REGION: o nome da
região do Google Cloud em que você quer implantar sua função
(por exemplo,
us-west1
). - YOUR_BUCKET_NAME: o nome do bucket do Cloud Storage que
aciona a função. Ao implantar funções de 2a geração, especifique apenas o nome do bucket,
sem o
gs://
principal. por exemplo,--trigger-event-filters="bucket=my-bucket"
.
Arquivamento do objeto: acione a função
Para acionar a função:
Crie um arquivo vazio
test-archive.txt
no diretório em que o código de amostra está localizado.Verifique se o controle de versão do seu bucket está ativado:
gsutil versioning set on gs://YOUR_BUCKET_NAME
Faça upload do arquivo no Cloud Storage:
gsutil cp test-archive.txt gs://YOUR_BUCKET_NAME
em que
YOUR_BUCKET_NAME
é o nome do bucket do Cloud Storage onde será feito o upload de um arquivo de teste. Neste momento, a função ainda não é executada.Arquive o arquivo para acionar a função:
gsutil rm gs://YOUR_BUCKET_NAME/test-archive.txt
Você verá o CloudEvent recebido nos registros:
gcloud functions logs read YOUR_FUNCTION_NAME --region REGION --gen2 --limit=10
Atualização de metadados do objeto
Os eventos de atualização de metadados são acionados quando os metadados do objeto existente são atualizados.
Atualização de metadados do objeto: implante a função
Usando o mesmo código de amostra do exemplo final, implante a função com atualização de metadados como o evento gatilho. Execute o seguinte comando no diretório em que o código de amostra está localizado:
Node.js
gcloud functions deploy nodejs-metadata-function \ --gen2 \ --runtime=nodejs20 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.
Python
gcloud functions deploy python-metadata-function \ --gen2 \ --runtime=python312 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.
Go
gcloud functions deploy go-metadata-function \ --gen2 \ --runtime=go121 \ --region=REGION
\ --source=. \ --entry-point=HelloStorage \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.
Java
gcloud functions deploy java-metadata-function \ --gen2 \ --runtime=java17 \ --region=REGION
\ --source=. \ --entry-point=functions.HelloGcs \ --memory=512MB \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.
C#
gcloud functions deploy csharp-metadata-function \ --gen2 \ --runtime=dotnet6 \ --region=REGION
\ --source=. \ --entry-point=HelloGcs.Function \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do .NET compatível a fim de executar a função.
Ruby
gcloud functions deploy ruby-metadata-function \ --gen2 \ --runtime=ruby32 \ --region=REGION
\ --source=. \ --entry-point=hello_gcs \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.
PHP
gcloud functions deploy php-metadata-function \ --gen2 \ --runtime=php82 \ --region=REGION
\ --source=. \ --entry-point=helloGCS \
--trigger-event-filters="type=google.cloud.storage.object.v1.metadataUpdated" \
--trigger-event-filters="bucket=YOUR_BUCKET_NAME"
Use a flag --runtime
para especificar o ID do ambiente de execução de uma
versão do PHP compatível a fim de executar
a função.
Substitua:
- REGION: o nome da
região do Google Cloud em que você quer implantar sua função
(por exemplo,
us-west1
). - YOUR_BUCKET_NAME: o nome do bucket do Cloud Storage que
aciona a função. Ao implantar funções de 2a geração, especifique apenas o nome do bucket,
sem o
gs://
principal. por exemplo,--trigger-event-filters="bucket=my-bucket"
.
Atualização de metadados do objeto: acionar a função
Para acionar a função:
Crie um arquivo vazio
test-metadata.txt
no diretório em que o código de amostra está localizado.Verifique se o bucket não tem controle de versão:
gsutil versioning set off gs://YOUR_BUCKET_NAME
Faça upload do arquivo no Cloud Storage:
gsutil cp test-metadata.txt gs://YOUR_BUCKET_NAME
em que
YOUR_BUCKET_NAME
é o nome do bucket do Cloud Storage onde será feito o upload de um arquivo de teste. Neste momento, a função ainda não é executada.Atualize os metadados do arquivo:
gsutil -m setmeta -h "Content-Type:text/plain" gs://YOUR_BUCKET_NAME/test-metadata.txt
Você verá o CloudEvent recebido nos registros:
gcloud functions logs read YOUR_FUNCTION_NAME --region REGION --gen2 --limit=10
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Exclua o projeto
O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.
Para excluir o projeto:
- 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.
Excluir os Cloud Functions
A exclusão de Cloud Functions não remove nenhum recurso armazenado no Cloud Storage.
Para excluir o Cloud Function criado neste tutorial, execute o seguinte comando:
gcloud functions delete YOUR_FUNCTION_NAME --gen2 --region REGION
Também é possível excluir o Cloud Functions do Console do Google Cloud.