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

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.

A preparar a aplicação

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

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

    Ir 

    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.

  3. 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/

    Ir 

    cd golang-samples/functions/helloworld/

    Java 

    cd java-docs-samples/functions/helloworld/hello-gcs/

    Ruby 

    cd ruby-docs-samples/functions/helloworld/storage/

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.

Finalização do objeto: implementação da função

Veja a função de exemplo, que processa 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"]))

Ir 


// 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 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 nodejs22 \
--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.

Ir 

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:

  1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

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

  3. Verifique os registos para se certificar de que as execuções foram concluídas:

    gcloud functions logs read --limit 50

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 nodejs22 \
--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.

Ir 

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:

  1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

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

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

  4. Elimine o ficheiro para acionar a função:

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

  5. Verifique os registos para se certificar de que as execuções foram concluídas:

    gcloud functions logs read --limit 50

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 nodejs22 \
--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.

Ir 

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:

  1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

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

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

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

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

  5. Monitorize os registos para se certificar de que as execuções foram concluídas:

    gcloud functions logs read --limit 50

Atualização dos metadados do objeto

Os eventos de atualização de metadados são acionados quando os metadados de um 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 nodejs22 \
--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.

Ir 

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:

  1. Crie um ficheiro gcf-test.txt vazio no diretório onde se encontra o código de exemplo.

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

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

  4. Atualize os metadados do ficheiro:

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

  5. Monitorize os registos para se certificar de que as execuções foram concluídas:

    gcloud functions logs read --limit 50