Déclencheurs Google Cloud Storage

Cloud Functions utilise des fonctions basées sur des événements pour gérer les événements de votre infrastructure Cloud. Par exemple, 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 sont fournis au format API JSON Cloud Storage.

Remarque : Les déclencheurs Cloud Storage utilisent Cloud Pub/Sub, ce qui signifie une distribution de type "au moins une fois". Remarque : Les déclencheurs Cloud Storage utilisent Cloud Pub/Sub, ce qui signifie une distribution de type "au moins une fois".

Les fonctions déclenchées par Storage acceptent quatre types de déclencheurs. Ces valeurs de type de déclencheur sont utilisées lors du déploiement de la fonction pour spécifier les événements Cloud Storage qui déclencheront vos fonctions :

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

• google.storage.object.delete

• google.storage.object.archive

• google.storage.object.metadataUpdate

Exemple de code de fonction

L'exemple de fonction suivant enregistre les données pertinentes lorsqu'un événement se produit.

Vous spécifiez le type de déclencheur lorsque vous déployez la fonction. Par exemple, l'exemple de déploiement ci-dessous utilise la fonction pour consigner chaque occurrence d'une création d'objet en spécifiant le type de déclencheur google.storage.object.finalize.

Pour accéder à un tutoriel complet sur l'exécution de ce code, consultez le tutoriel Cloud Storage :

Node.js

 

functions/helloworld/index.js

Afficher sur GitHub Commentaires

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

 

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,
       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('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(ny) 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;

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

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
{
     /// <summary>
     /// Example Cloud Storage-triggered function.
     /// This function can process any event from Cloud Storage.
     /// </summary>
    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;
        }
    }
}

Ruby

functions/helloworld/storage/app.rb

Afficher sur GitHubCommentaires

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

PHP

functions/helloworld_storage/index.php

Afficher sur GitHub Commentaires

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloGCS', 'helloGCS');

function helloGCS(CloudEventInterface $cloudevent)
{
    // This function supports all Cloud Storage event types.
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');
    $data = $cloudevent->getData();
    fwrite($log, 'Event: ' . $cloudevent->getId() . PHP_EOL);
    fwrite($log, 'Event Type: ' . $cloudevent->getType() . PHP_EOL);
    fwrite($log, 'Bucket: ' . $data['bucket'] . PHP_EOL);
    fwrite($log, 'File: ' . $data['name'] . PHP_EOL);
    fwrite($log, 'Metageneration: ' . $data['metageneration'] . PHP_EOL);
    fwrite($log, 'Created: ' . $data['timeCreated'] . PHP_EOL);
    fwrite($log, 'Updated: ' . $data['updated'] . PHP_EOL);
}

Spécifier le type de déclencheur lors du déploiement

La commande gcloud suivante déploie la fonction avec un déclencheur object.finalize.

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs16 \
--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 :

• nodejs16 (recommandé)
• nodejs14
• nodejs12
• nodejs10

Python

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

• python310 (version bêta)
• python39 (recommandé)
• python38
• python37

Go

gcloud functions deploy HelloGCS \
--runtime go116 \
--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 :

• go116 (recommandé)
• go113
• go111

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java11 \
--memory 512MB \
--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 Java :

• java17 (version bêta)
• java11 (recommandé)

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

Ruby

gcloud functions deploy hello_gcs --runtime ruby30 \
--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 Ruby :

• ruby30 (recommandé)
• ruby27
• ruby26

PHP

gcloud functions deploy helloGCS --runtime php74 \
--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 PHP :

• php81 (version bêta)
• php74 (recommandé)

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

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).

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. Les événements sont soumis aux garanties de diffusion de Pub/Sub.

Limites des notifications

Un bucket peut comporter jusqu'à 10 configurations de notification déclenchant un événement spécifique. Configurer trop de notifications sur le même bucket peut vous faire dépasser 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

Si vous atteignez la limite, vous ne pourrez pas créer de fonction tant que vous n'aurez pas entrepris d'actions correctives, telles que la suppression de notifications.

Découvrez les quotas et les limites de requêtes pour Cloud Storage.

Autorisations

Vous devez disposer des autorisations suffisantes sur le projet qui recevra les notifications. Cela implique d'effectuer les opérations suivantes :

1. Obtenir l'adresse e-mail de l'agent de service associé au projet contenant votre bucket Cloud Storage.

2. Utiliser l'adresse e-mail obtenue à l'étape précédente pour octroyer à l'agent de service le rôle IAM pubsub.publisher pour le sujet Pub/Sub concerné.

   Remarque : Plusieurs secondes peuvent s'écouler entre l'attribution du rôle et son application à votre agent de service. Si vous accordez cette autorisation de manière automatisée, attendez 30 secondes avant de configurer Cloud Storage.

Apprenez-en plus sur la configuration des notifications Pub/Sub pour Cloud Storage.

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 acceptées dans 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 sur Cloud Storage pour obtenir un exemple de mise en œuvre d'une fonction basée sur des événements déclenchée par Cloud Storage.