Tutorial de Cloud Storage (1.ª gen.)

En este sencillo tutorial se muestra cómo escribir, desplegar 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 ejemplos de código para usar Cloud Storage, visita el navegador de ejemplos de Google Cloud.

Objetivos

• Escribe y despliega una función de Cloud Run basada en eventos.
• Activa la función subiendo un archivo a Cloud Storage.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

• Cloud Run functions
• Cloud Storage

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Antes de empezar

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente 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 the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Si ya tienes instalada la CLI de gcloud, actualízala ejecutando el siguiente comando:

gcloud components update

1. Prepara tu entorno de desarrollo:

   Node.js

   Ir a la guía de configuración de Node.js

   Python

   Ir a la guía de configuración de Python

   Go

   Ve a la guía de configuración de Go

   Java

   Ir a la guía de configuración de Java

   Ruby

   Ir a la guía de configuración de Ruby

Preparar la aplicación

1. Crea un segmento de Cloud Storage para subir un archivo de prueba, donde YOUR_TRIGGER_BUCKET_NAME es un nombre de segmento único a nivel global:

   gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME

2. Clona el repositorio de aplicaciones de muestra en la máquina local:

   Node.js

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

   También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

   Python

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

   También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

   Go

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

   También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

   Java

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

   También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

   Ruby

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

   También puedes descargar el ejemplo como un archivo ZIP y extraerlo.

3. Cambia al directorio que contiene el código de ejemplo de Cloud Run Functions:

   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/

Desplegar y activar la función

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

• finalize

• delete

• archive

• actualización de metadatos

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

Finalización de objeto

Los eventos de finalización de objetos se activan cuando se finaliza correctamente una "escritura" de un objeto de Cloud Storage. En concreto, esto significa que se activa cuando se crea un objeto o se sobrescribe uno ya disponible. Este activador ignora las operaciones de actualización de archivos y metadatos.

Object Finalize: implementar la función

Echa un vistazo a la función de ejemplo, que gestiona 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 desplegar 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 nodejs20 \
--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 tu 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 tiempo de ejecución de una versión de Python compatible para ejecutar tu 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 tiempo 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 de tiempo 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 tiempo de ejecución de una versión de Ruby compatible para ejecutar tu función.

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

Finalización de objetos: activación de la función

Para activar la función, haz lo siguiente:

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

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

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

   donde YOUR_TRIGGER_BUCKET_NAME es el nombre del segmento de Cloud Storage en el que subirás un archivo de prueba.

3. Consulta los registros para asegurarte de que las ejecuciones se han completado:

   gcloud functions logs read --limit 50
   

Eliminación de objeto

Los eventos de eliminación de objetos se activan cuando se elimina de forma no definitiva un objeto. Esto ocurre cuando se sobrescribe o se elimina un objeto de un segmento en el que no está habilitada la gestión de versiones de objetos. Si eliminas un objeto especificando su número de generación, también se eliminará de forma lógica.

Object Delete: deploying the function

Usando el mismo código de muestra que en el ejemplo de finalización, implementa la función con la eliminación de objetos como evento de activación. Ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--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 tu 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 tiempo de ejecución de una versión de Python compatible para ejecutar tu 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 tiempo 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 de tiempo 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 tiempo de ejecución de una versión de Ruby compatible para ejecutar tu función.

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

Eliminación de objetos: activa la función.

Para activar la función, haz lo siguiente:

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

2. Asegúrate de que tu cubo no tenga 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

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

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

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

5. Consulta los registros para asegurarte de que las ejecuciones se han completado:

   gcloud functions logs read --limit 50
   

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

Archivado de objeto

Los eventos de archivo de objetos se activan cuando la versión activa de un objeto se convierte en una versión no actual. Esto ocurre cuando se sobrescribe o se elimina un objeto en un segmento en el que la gestión de versiones de objetos está habilitada.

Object Archive: desplegar la función

Usando el mismo código de muestra que en el ejemplo de finalización, implementa la función con el archivo de objeto como evento de activación. Ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--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 tu 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 tiempo de ejecución de una versión de Python compatible para ejecutar tu 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 tiempo 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 de tiempo 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 tiempo de ejecución de una versión de Ruby compatible para ejecutar tu función.

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

Archivo de objetos: activación de la función

Para activar la función, haz lo siguiente:

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

2. Asegúrate de que la gestión de versiones esté habilitada en tu segmento:

   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

   donde YOUR_TRIGGER_BUCKET_NAME es el nombre del segmento de Cloud Storage en el 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. Consulta los registros para asegurarte de que las ejecuciones se han completado:

   gcloud functions logs read --limit 50
   

Actualización de metadatos de objeto

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

Actualización de metadatos de objetos: implementación de la función

Usando el mismo código de muestra que en el ejemplo de finalización, despliega la función con la actualización de metadatos como evento de activación. Ejecuta el siguiente comando en el directorio donde se encuentra el código de muestra:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--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 tu 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 tiempo de ejecución de una versión de Python compatible para ejecutar tu 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 tiempo 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 de tiempo 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 tiempo de ejecución de una versión de Ruby compatible para ejecutar tu función.

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

Actualización de metadatos de objetos: activación de la función

Para activar la función, haz lo siguiente:

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

2. Asegúrate de que tu cubo no tenga 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

   donde YOUR_TRIGGER_BUCKET_NAME es el nombre del segmento de Cloud Storage en el 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. Consulta los registros para asegurarte de que las ejecuciones se han completado:

   gcloud functions logs read --limit 50
   

Limpieza

Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

Eliminar el proyecto

La forma más fácil de evitar que te cobren es eliminar el proyecto que has creado para el tutorial.

Para ello, sigue las instrucciones que aparecen a continuación:

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Eliminar la función

Si eliminas funciones de Cloud Run, no se eliminarán los recursos almacenados en Cloud Storage.

Para eliminar la función que has creado en este tutorial, ejecuta el siguiente 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 

También puedes eliminar funciones de Cloud Run desde la Google Cloud consola.

Siguientes pasos

• Consulta cómo realizar un OCR en imágenes subidas a un segmento.
• Consulta cómo traducir archivos de texto con funciones de Cloud Run.