Instructivo de Cloud Storage (1st gen)

En este sencillo instructivo, se muestra cómo escribir, implementar y activar una función de Cloud Run basada en eventos con un activador de Cloud Storage para responder a eventos de Cloud Storage.

Si buscas muestras de código para usar Cloud Storage, visita el navegador de muestra de Google Cloud.

Prepara la aplicación

  1. Crea un depósito de Cloud Storage para subir un archivo de prueba, en el que YOUR_TRIGGER_BUCKET_NAME es un nombre de depósito único a nivel global:

    gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME

  2. Clona el repositorio de la aplicación de muestra en tu máquina local:

    Node.js 

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

    Python 

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

    Go

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

    Java 

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

    Ruby 

    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

  3. Ve al directorio que contiene el código de muestra de funciones de 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/

Implementa y activa la función

Las funciones de Cloud Storage se basan en notificaciones de Pub/Sub desde Cloud Storage y admiten tipos de eventos similares:

En las siguientes secciones, se describe cómo implementar y activar una función para cada uno de estos tipos de eventos.

Finalización del objeto

Los eventos de finalización del objeto se activan cuando una operación de “escritura” de un objeto de Cloud Storage se finaliza correctamente. En particular, esto significa que crear un objeto nuevo o reemplazar uno existente activa este evento. Este activador ignora las operaciones de actualización de archivo y metadatos.

Finalización del objeto: Implementa la función

Consulta la función de muestra que maneja los eventos de 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 implementar la función, ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión compatible de Node.js para ejecutar la función.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Python compatible para ejecutar la función.

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Go compatible para ejecutar tu función.

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

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión de Java compatible para ejecutar tu función.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Ruby compatible para ejecutar tu función.

donde YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage que activa la función.

Finalización del objeto: activa la función

Sigue estos pasos para activar la función:

  1. Crea un archivo gcf-test.txt vacío en el directorio donde se encuentra el código de muestra.

  2. Sube el archivo a Cloud Storage para activar la función:

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

    en el que YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage al que subirás un archivo de prueba.

  3. Verifica los registros para asegurarte de que las ejecuciones se completaron:

    gcloud functions logs read --limit 50

Eliminación del objeto

Los eventos de eliminación de objetos se activan cuando un objeto se borra de forma no definitiva. Esto sucede cuando un objeto se reemplaza o se borra en un bucket sin el control de versiones de objetos habilitado. Si borras un objeto especificando su número de generación, también se borrará de forma no definitiva.

Eliminación del objeto: implementa la función

Con el mismo código de muestra que en el ejemplo de finalización, implementa la función con el evento de eliminación del objeto como su activador. Ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión compatible de Node.js para ejecutar la función.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Python compatible para ejecutar la función.

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Go compatible para ejecutar tu función.

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

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión de Java compatible para ejecutar tu función.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Ruby compatible para ejecutar tu función.

donde YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage que activa la función.

Eliminación del objeto: activa la función

Sigue estos pasos para activar la función:

  1. Crea un archivo gcf-test.txt vacío en el directorio donde se encuentra el código de muestra.

  2. Asegúrate de que tu bucket no tenga control de versiones:

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

  3. Sube el archivo a Cloud Storage:

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

    en el que YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage al que subirás un archivo de prueba. En este punto, la función aún no debería ejecutarse.

  4. Borra el archivo para activar la función:

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

  5. Verifica los registros para asegurarte de que las ejecuciones se completaron:

    gcloud functions logs read --limit 50

Ten en cuenta que la función puede tardar algún tiempo en terminar de ejecutarse.

Archivado del objeto

Los eventos de archivo de objetos se activan cuando una versión publicada de un objeto se convierte en una versión no actual. Esto sucede cuando un objeto se reemplaza o se borra en un bucket con el control de versiones de objetos habilitado.

Archivado del objeto: implementa la función

Con el mismo código de muestra que en el ejemplo de finalización, implementa la función con el evento de archivado del objeto como su activador. Ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión compatible de Node.js para ejecutar la función.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Python compatible para ejecutar la función.

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Go compatible para ejecutar tu función.

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

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión de Java compatible para ejecutar tu función.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Ruby compatible para ejecutar tu función.

donde YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage que activa la función.

Archivado del objeto: activa la función

Sigue estos pasos para activar la función:

  1. Crea un archivo gcf-test.txt vacío en el directorio donde se encuentra el código de muestra.

  2. Asegúrate de que tu bucket tenga el control de versiones habilitado:

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

  3. Sube el archivo a Cloud Storage:

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

    en el que YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage al que subirás un archivo de prueba. En este punto, la función aún no debería ejecutarse.

  4. Archiva el archivo para activar la función:

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

  5. Revisa los registros para asegurarte de que las ejecuciones se completaron:

    gcloud functions logs read --limit 50

Actualización de metadatos del objeto

Los eventos de actualización de metadatos del objeto se activan cuando se actualizan los metadatos del objeto existente.

Actualización de metadatos del objeto: Implementa la función

Con el mismo código de muestra que en el ejemplo de finalización, implementa la función con el evento de actualización de metadatos del objeto como su activador. Ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión compatible de Node.js para ejecutar la función.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Python compatible para ejecutar la función.

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Go compatible para ejecutar tu función.

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

Usa la marca --runtime para especificar el ID del entorno de ejecución de una versión de Java compatible para ejecutar tu función.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Usa la marca --runtime para especificar el ID de entorno de ejecución de una versión de Ruby compatible para ejecutar tu función.

donde YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage que activa la función.

Actualización de metadatos del objeto: activa la función

Sigue estos pasos para activar la función:

  1. Crea un archivo gcf-test.txt vacío en el directorio donde se encuentra el código de muestra.

  2. Asegúrate de que tu bucket no tenga control de versiones:

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

  3. Sube el archivo a Cloud Storage:

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

    en el que YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage al que subirás un archivo de prueba. En este punto, la función aún no debería ejecutarse.

  4. Actualiza los metadatos del archivo:

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

  5. Revisa los registros para asegurarte de que las ejecuciones se completaron:

    gcloud functions logs read --limit 50