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.

Remarque : Cloud Functions ne peut être déclenché que par des buckets Cloud Storage situés dans le même projet Google Cloud Platform.

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.

Remarque : Les déclencheurs Cloud Storage utilisent Cloud Pub/Sub, ce qui signifie une distribution de type "au moins une fois". Par conséquent, votre fonction peut s'exécuter plusieurs fois pour un événement donné.

Les types de déclencheurs disponibles sont les suivants :

• google.storage.object.finalize (par défaut)

• 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} 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

 

functions/helloworld/main.py

Afficher sur GitHub Commentaires

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.

    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 Stackdriver Logging
    """

    print('Event ID: {}'.format(context.event_id))
    print('Event type: {}'.format(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

 

functions/helloworld/hello_cloud_storage.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"`
}

// HelloGCS consumes a GCS event.
func HelloGCS(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/src/main/java/functions/HelloGcs.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 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());
  }
}

C#

functions/helloworld/HelloGcs/Function.cs

Afficher sur GitHub Commentaires

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloGcs
{
    public class Function : ICloudEventFunction<StorageObjectData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
        {
            _logger.LogInformation("Event: {event}", cloudEvent.Id);
            _logger.LogInformation("Event Type: {type}", cloudEvent.Type);
            _logger.LogInformation("Bucket: {bucket}", data.Bucket);
            _logger.LogInformation("File: {file}", data.Name);
            _logger.LogInformation("Metageneration: {metageneration}", data.Metageneration);
            _logger.LogInformation("Created: {created:s}", data.TimeCreated?.ToDateTimeOffset());
            _logger.LogInformation("Updated: {updated:s}", data.Updated?.ToDateTimeOffset());
            return Task.CompletedTask;
        }
    }
}

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 helloGCS \
--runtime nodejs10 \
--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 Node.js :

• nodejs10
• nodejs12

Python

gcloud functions deploy hello_gcs \
--runtime python37 \
--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 Python :

• python37
• python38

Go

gcloud functions deploy HelloGCS \
--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 HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

C#

gcloud functions deploy csharp-gcs-function \
--entry-point HelloGcs.Function \
--runtime dotnet3 \
--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.