Tutorial do Cloud Storage (1ª geração)

Neste tutorial básico, demonstraremos como escrever, implantar e acionar uma função do Cloud Run orientada a eventos com um gatilho do Cloud Storage para responder a eventos do Cloud Storage.

Observação: os eventos são entregues usando notificações do Pub/Sub do Cloud Storage. Um bucket pode ter até 10 configurações de notificação definidas para acionar um determinado evento; A configuração de muitas notificações para o mesmo bucket pode exceder o limite de notificações do bucket e impossibilitar a criação de uma função, conforme indicado pelo erro Cloud Storage bucket ...: Pub/Sub notification limit reached. Se você atingir o limite, não será possível criar uma função até tomar medidas corretivas, como remover as notificações.

Se você está procurando amostras de código para usar o Cloud Storage em si, acesse a pesquisa de exemplos de código do Google Cloud do Google Cloud.

Como preparar o aplicativo

1. Crie um bucket do Cloud Storage para fazer upload de um arquivo de teste, em que YOUR_TRIGGER_BUCKET_NAME é um nome de bucket globalmente exclusivo:

   gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME

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

   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.

3. Mude para o diretório que contém o código de amostra 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/

Como 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:

• finalize

• delete

• archive

• metadata update

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.

Finalização do objeto: como implantar a função

Confira a amostra da função, que processa os eventos do Cloud Storage:

Node.js

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 * This sample works for all Cloud Storage CRUD operations.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (file, context) => {
  console.log(`  Event: ${context.eventId}`);
  console.log(`  Event Type: ${context.eventType}`);
  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

def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed,
       and works for all Cloud Storage CRUD operations.
    Args:
        event (dict):  The dictionary with data specific to this type of event.
                       The `data` field contains a description of the event in
                       the Cloud Storage `object` format described here:
                       https://cloud.google.com/storage/docs/json_api/v1/objects#resource
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Cloud Logging
    """

    print(f"Event ID: {context.event_id}")
    print(f"Event type: {context.event_type}")
    print("Bucket: {}".format(event["bucket"]))
    print("File: {}".format(event["name"]))
    print("Metageneration: {}".format(event["metageneration"]))
    print("Created: {}".format(event["timeCreated"]))
    print("Updated: {}".format(event["updated"]))

Go

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/functions/metadata"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Kind                    string                 `json:"kind"`
	ID                      string                 `json:"id"`
	SelfLink                string                 `json:"selfLink"`
	Name                    string                 `json:"name"`
	Bucket                  string                 `json:"bucket"`
	Generation              string                 `json:"generation"`
	Metageneration          string                 `json:"metageneration"`
	ContentType             string                 `json:"contentType"`
	TimeCreated             time.Time              `json:"timeCreated"`
	Updated                 time.Time              `json:"updated"`
	TemporaryHold           bool                   `json:"temporaryHold"`
	EventBasedHold          bool                   `json:"eventBasedHold"`
	RetentionExpirationTime time.Time              `json:"retentionExpirationTime"`
	StorageClass            string                 `json:"storageClass"`
	TimeStorageClassUpdated time.Time              `json:"timeStorageClassUpdated"`
	Size                    string                 `json:"size"`
	MD5Hash                 string                 `json:"md5Hash"`
	MediaLink               string                 `json:"mediaLink"`
	ContentEncoding         string                 `json:"contentEncoding"`
	ContentDisposition      string                 `json:"contentDisposition"`
	CacheControl            string                 `json:"cacheControl"`
	Metadata                map[string]interface{} `json:"metadata"`
	CRC32C                  string                 `json:"crc32c"`
	ComponentCount          int                    `json:"componentCount"`
	Etag                    string                 `json:"etag"`
	CustomerEncryption      struct {
		EncryptionAlgorithm string `json:"encryptionAlgorithm"`
		KeySha256           string `json:"keySha256"`
	}
	KMSKeyName    string `json:"kmsKeyName"`
	ResourceState string `json:"resourceState"`
}

// HelloGCS consumes a(ny) GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %w", err)
	}
	log.Printf("Event ID: %v\n", meta.EventID)
	log.Printf("Event type: %v\n", meta.EventType)
	log.Printf("Bucket: %v\n", e.Bucket)
	log.Printf("File: %v\n", e.Name)
	log.Printf("Metageneration: %v\n", e.Metageneration)
	log.Printf("Created: %v\n", e.TimeCreated)
	log.Printf("Updated: %v\n", e.Updated)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.GcsEvent;
import java.util.logging.Logger;

/**
 * Example Cloud Storage-triggered function.
 * This function can process any event from Cloud Storage.
 */
public class HelloGcs implements BackgroundFunction<GcsEvent> {
  private static final Logger logger = Logger.getLogger(HelloGcs.class.getName());

  @Override
  public void accept(GcsEvent event, Context context) {
    logger.info("Event: " + context.eventId());
    logger.info("Event Type: " + context.eventType());
    logger.info("Bucket: " + event.getBucket());
    logger.info("File: " + event.getName());
    logger.info("Metageneration: " + event.getMetageneration());
    logger.info("Created: " + event.getTimeCreated());
    logger.info("Updated: " + event.getUpdated());
  }
}

Ruby

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # The `event` parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

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 helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

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 hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

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 HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

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-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 do ambiente de execução de uma versão compatível do Java a fim de executar a 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 do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.

em que YOUR_TRIGGER_BUCKET_NAME é o nome do bucket do Cloud Storage que aciona a função.

Finalização do objeto: como acionar a função

Para acionar a função:

1. Crie um arquivo vazio gcf-test.txt no diretório em que o código de amostra está localizado.

2. Faça upload do arquivo no Cloud Storage para acionar a função:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   em que YOUR_TRIGGER_BUCKET_NAME é o nome do bucket do Cloud Storage onde será feito o upload de um arquivo de teste.

3. Verifique os registros para confirmar se execuções foram concluídas:

   gcloud functions logs read --limit 50
   

Exclusão do objeto

Os eventos de exclusão de objeto são acionados quando um objeto é excluído de maneira reversível. Isso acontece quando um objeto é substituído ou excluído em um bucket sem o controle de versões de objetos ativado. A exclusão de um objeto especificando o número de geração também resulta na exclusão reversível do objeto.

Exclusão do objeto: como 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 helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

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 hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

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 HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

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-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 do ambiente de execução de uma versão compatível do Java a fim de executar a 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 do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.

em que YOUR_TRIGGER_BUCKET_NAME é o nome do bucket do Cloud Storage que aciona a função.

Exclusão do objeto: como acionar a função

Para acionar a função:

1. Crie um arquivo vazio gcf-test.txt no diretório em que o código de amostra está localizado.

2. Verifique se o bucket não tem controle de versão:

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

3. Faça upload do arquivo no Cloud Storage:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   em que YOUR_TRIGGER_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.

4. Exclua o arquivo para acionar a função:

   gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt

5. Verifique os registros para confirmar se execuções foram concluídas:

   gcloud functions logs read --limit 50
   

Observe que a execução da função pode levar algum tempo para ser concluída.

Arquivamento do objeto

Os eventos de arquivamento de objetos são acionados quando uma versão ativa de um objeto se torna uma versão não atual. Isso acontece quando um objeto é substituído ou excluído em um bucket com o controle de versões de objetos ativado.

Arquivamento do objeto: como implantar 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 helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

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 hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

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 HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

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-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 do ambiente de execução de uma versão compatível do Java a fim de executar a 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 do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.

em que YOUR_TRIGGER_BUCKET_NAME é o nome do bucket do Cloud Storage que aciona a função.

Arquivamento do objeto: como acionar a função

Para acionar a função:

1. Crie um arquivo vazio gcf-test.txt no diretório em que o código de amostra está localizado.

2. Verifique se o controle de versão do seu bucket está ativado:

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --versioning

3. Faça upload do arquivo no Cloud Storage:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   em que YOUR_TRIGGER_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.

4. Arquive o arquivo para acionar a função:

   gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt

5. Verifique os registros para ter certeza de que as execuções foram concluídas:

   gcloud functions logs read --limit 50
   

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: como implantar 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 helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

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 hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

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 HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

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-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 do ambiente de execução de uma versão compatível do Java a fim de executar a 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 do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.

em que YOUR_TRIGGER_BUCKET_NAME é o nome do bucket do Cloud Storage que aciona a função.

Atualização de metadados do objeto: como acionar a função

Para acionar a função:

1. Crie um arquivo vazio gcf-test.txt no diretório em que o código de amostra está localizado.

2. Verifique se o bucket não tem controle de versão:

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

3. Faça upload do arquivo no Cloud Storage:

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   em que YOUR_TRIGGER_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.

4. Atualize os metadados do arquivo:

   gcloud storage objects update gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt --content-type=text/plain

5. Verifique os registros para ter certeza de que as execuções foram concluídas:

   gcloud functions logs read --limit 50