Activadores de Google Cloud Storage

Cloud Functions puede responder a las notificaciones de cambios que surgen de Google Cloud Storage. Estas notificaciones se pueden configurar para activarse en respuesta a varios eventos dentro de un depósito, como la creación, la eliminación, el archivado y las actualizaciones de metadatos de objetos.

Tipos de eventos

Los eventos de Cloud Storage que usa Cloud Functions se basan en Notificaciones de Cloud Pub/Sub para Google Cloud Storage y se pueden configurar de forma similar.

Los valores admitidos de tipos de activadores son los siguientes:

  • google.storage.object.finalize

  • google.storage.object.delete

  • google.storage.object.archive

  • google.storage.object.metadataUpdate

Finalización del objeto

Valor del tipo de activador: google.storage.object.finalize

Este evento se envía cuando se crea un objeto nuevo (o se sobrescribe un objeto existente y se crea una generación nueva de ese objeto) en el depósito.

Por ejemplo, la siguiente función registra datos pertinentes cuando ocurre un evento:

Node.js

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 * @param {function} callback The callback function.
 */
exports.helloGCS = (file, context, callback) => {
  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}`);

  callback();
};

Python

def hello_gcs(data, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed.

    Args:
        data (dict): The Cloud Functions event payload.
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Stackdriver Logging
    """

    print('Event ID: {}'.format(context.event_id))
    print('Event type: {}'.format(context.event_type))
    print('Bucket: {}'.format(data['bucket']))
    print('File: {}'.format(data['name']))
    print('Metageneration: {}'.format(data['metageneration']))
    print('Created: {}'.format(data['timeCreated']))
    print('Updated: {}'.format(data['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"`
}

// HelloGCSInfo prints information about a GCS event.
func HelloGCSInfo(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %v", 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;

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());
  }
}

Para implementar la función con un activador de finalización del objeto, ejecuta el siguiente comando en el directorio que contiene el código de función:

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs10 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Puedes usar los siguientes valores para que con la marca --runtime se especifique tu versión preferida de Node.js:
  • nodejs10
  • nodejs12

Python

gcloud functions deploy hello_gcs \
--runtime python37 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Puedes usar los siguientes valores para que la marca --runtime especifique tu versión preferida de Python:
  • python37
  • python38

Go

gcloud functions deploy HelloGCSInfo \
--runtime go111 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Puedes usar los siguientes valores en la marca --runtime para especificar tu versión preferida de Go:
  • go111
  • go113

Java

gcloud functions deploy java-gcs-function \
--entry-point HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

En este comando YOUR_TRIGGER_BUCKET_NAME es el nombre del depósito de Cloud Storage que supervisará la función.

Eliminación del objeto

Valor del tipo de activador: google.storage.object.delete

Este evento se envía cuando se borra un objeto de manera permanente. Según la configuración del control de versiones del objeto de un depósito, esto significa lo siguiente:

  • En el caso de los depósitos con control de versiones, este solo se envía cuando se borra una versión de manera permanente (pero no cuando se archiva un objeto).

  • En el caso de los depósitos sin control de versiones, este se envía cuando se borra o se sobrescribe un objeto.

Archivado del objeto

Valor del tipo de activador: google.storage.object.archive

Este evento se envía cuando una versión publicada de un objeto se archiva o se borra.

Este evento solo se envía para depósitos con control de versiones.

Actualización de metadatos del objeto

Valor del tipo de activador: google.storage.object.metadataUpdate

Este evento se envía cuando los metadatos de un objeto existente cambian.

Estructura de eventos

Los datos de eventos de almacenamiento se entregan en el formato object de Cloud Storage.

Mecanismo de entrega de eventos

Los eventos se entregan con las notificaciones de Pub/Sub desde Cloud Storage. La configuración de demasiadas funciones en el mismo depósito puede agotar el límite de notificaciones de este y, también, puede imposibilitar la creación de la función, como se indica en el error Cloud Storage bucket ...: Pub/Sub notification limit reached. Consulta la documentación de Notificaciones de Cloud Pub/Sub para Google Cloud Storage a fin de obtener más información sobre los límites de notificaciones.

Activadores de Cloud Storage heredados

El comando de gcloud que aparece a continuación implementa una función que se activa con notificaciones de cambio de objeto heredadas en un depósito específico. En general, las notificaciones de Cloud Pub/Sub son más fáciles de usar, más flexibles y más potentes que las de cambio de objeto. Sin embargo, estas notificaciones heredadas son compatibles con las funciones heredadas que ya consumen estos eventos.

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event providers/cloud.storage/eventTypes/object.change \
FLAGS...
Argumento Descripción
--trigger-resource NAME El nombre del depósito de Cloud Storage que la función vigila en busca de cambios.
--trigger-event NAME El nombre del tipo de evento que la función desea recibir. En este caso, es el evento object.change heredado.
FLAGS... Marcas adicionales que debes especificar durante la implementación, como --runtime. Para obtener una referencia completa, consulta la documentación de gcloud functions deploy.

Próximos pasos

Consulta el instructivo de Cloud Storage para ver un ejemplo de cómo implementar una función en segundo plano que se activa con Cloud Storage.