Déclencheurs Google Cloud Storage

Cloud Functions peut répondre à des notifications de modification provenant de Google Cloud Storage. Ces notifications peuvent être configurées de manière à se déclencher en réponse à divers événements à l’intérieur d’un bucket : création, suppression et archivage d'objets, ainsi que mises à jour de métadonnées.

Types d'événement

Les événements Cloud Storage utilisés par Cloud Functions sont basés sur les notifications Cloud Pub/Sub pour Google Cloud Storage, et peuvent être configurés de la même manière.

Les types de déclencheurs disponibles sont les suivants :

google.storage.object.finalize
google.storage.object.delete
google.storage.object.archive
google.storage.object.metadataUpdate

Finalisation de l'objet

Valeur du type de déclencheur : google.storage.object.finalize

Cet événement est envoyé lorsqu'un nouvel objet est créé dans le bucket (ou qu'un objet existant est remplacé et qu'une nouvelle génération de cet objet est créée).

Par exemple, la fonction suivante enregistre les données pertinentes lorsqu'un événement se produit :

Node.js

functions/helloworld/index.js

Afficher sur GitHub Commentaires

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloGCSGeneric = (data, context, callback) => {
  const file = data;

  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

functions/gcs/main.py

Afficher sur GitHub Commentaires

def hello_gcs_generic(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

functions/helloworld/storage_generic/hello_storage_generic.go

Afficher sur GitHub Commentaires


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

functions/helloworld/hello-gcs-generic/src/main/java/functions/HelloGcsGeneric.java

Afficher sur GitHub Commentaires


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

public class HelloGcsGeneric implements BackgroundFunction<GcsEvent> {
  private static final Logger logger = Logger.getLogger(HelloGcsGeneric.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());
  }
}

Pour déployer la fonction avec un déclencheur "finalisation de l'objet", exécutez la commande suivante dans le répertoire contenant le code de la fonction :

Node.js

gcloud functions deploy helloGCSGeneric --runtime nodejs10 --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event google.storage.object.finalize

Python

gcloud functions deploy hello_gcs_generic --runtime python37 --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event google.storage.object.finalize

Go

gcloud functions deploy HelloGCSInfo --runtime go111 --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event google.storage.object.finalize

Vous pouvez attribuer les valeurs suivantes à l'option --runtime, afin de spécifier votre version préférée de Go :

go111
go113

Java

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

où YOUR_TRIGGER_BUCKET_NAME est le nom du bucket Cloud Storage que la fonction surveillera.

Suppression de l'objet

Valeur du type de déclencheur : google.storage.object.delete

Cet événement est envoyé lorsqu'un objet est définitivement supprimé. En fonction du paramètre de gestion des versions d'objet des buckets, cela signifie :

pour les buckets avec gestion des versions, que celui-ci n'est envoyé que lorsqu'une version est définitivement supprimée (mais pas lorsqu'un objet est archivé) ;
pour les buckets sans gestion de versions, que celui-ci est envoyé lorsqu'un objet est supprimé ou écrasé.

Archivage de l'objet

Valeur du type de déclencheur : google.storage.object.archive

Cet événement est envoyé lorsqu'une version en ligne d'un objet est archivée ou supprimée.

Cet événement est uniquement envoyé pour les buckets avec gestion des versions.

Mise à jour des métadonnées de l'objet

Valeur du type de déclencheur : google.storage.object.metadataUpdate

Cet événement est envoyé lorsque les métadonnées d'un objet existant changent.

Structure de l'événement

Les données d'événements de stockage sont envoyées au format object Cloud Storage.

Mécanisme de diffusion d'événements

Les événements sont envoyés via des notifications Pub/Sub issues de Cloud Storage. Configurer trop de fonctions sur le même bucket peut vous rapprocher de la limite de notifications et empêcher la création d'une fonction, comme indiqué par l'erreur suivante : Cloud Storage bucket ...: Pub/Sub notification limit reached. Reportez-vous à la documentation sur les notifications Cloud Pub/Sub de Google Cloud Storage pour en savoir plus sur ces limites.

Anciens déclencheurs Cloud Storage

La commande gcloud ci-dessous déploie une fonction déclenchée par la réception d'anciennes notifications de changement d'objet sur un bucket spécifique. Généralement, les notifications Cloud Pub/Sub sont plus faciles à utiliser, plus flexibles et plus puissantes que les notifications de modification d'objet. Cependant, ces anciennes notifications sont prises en charge pour les anciennes fonctions qui utilisent déjà ces événements.

gcloud functions deploy YOUR_FUNCTION_NAME --trigger-resource YOUR_TRIGGER_BUCKET_NAME --trigger-event providers/cloud.storage/eventTypes/object.change FLAGS...

Argument	Description
`--trigger-resource NAME`	Nom du bucket Cloud Storage dont la fonction surveille les changements.
`--trigger-event NAME`	Nom du type d'événement que la fonction souhaite recevoir. Dans ce cas, il s'agit de l'ancien événement `object.change`.
`FLAGS...`	Options supplémentaires à spécifier lors du déploiement, telles que `--runtime`. Pour accéder aux informations complètes, consultez la documentation sur `gcloud functions deploy`.

Étapes suivantes

Reportez-vous au tutoriel Cloud Storage pour obtenir un exemple de mise en œuvre d'une fonction d'arrière-plan déclenchée par Cloud Storage.