Tutoriel sur Cloud Storage (1re génération)

Ce tutoriel simple montre comment écrire, déployer et déclencher une fonction Cloud Run basée sur des événements avec un déclencheur Cloud Storage pour répondre aux événements Cloud Storage.

Si vous recherchez des exemples de code pour utiliser Cloud Storage proprement dit, consultez l'exemple de navigateur Google Cloud.

Préparer l'application

  1. Créez un bucket Cloud Storage pour importer un fichier de test, avec un attribut de nom YOUR_TRIGGER_BUCKET_NAME encore jamais utilisé :

    gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME

  2. Clonez le dépôt de l'exemple d'application sur votre machine locale :

    Node.js 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Python 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Go 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Java

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

    Ruby 

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

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

  3. Accédez au répertoire contenant l'exemple de code 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/

Déployer et déclencher la fonction

Actuellement, les fonctions Cloud Storage sont basées sur les notifications Pub/Sub de Cloud Storage et acceptent des types d’événements similaires :

Les sections suivantes décrivent comment déployer et déclencher une fonction pour chacun de ces types d'événements.

Finalisation de l'objet

Les objets finalisent les événements quand une "écriture" d'un objet Cloud Storage est correctement finalisée. Cela signifie en particulier que la création d'un objet ou le remplacement d'un objet existant déclenche cet événement. Les opérations de mise à jour des archives et des métadonnées sont ignorées par ce déclencheur.

Finalisation de l'objet : déployer la fonction

Consultez l'exemple de fonction qui gère les événements 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

Pour déployer la fonction, exécutez la commande suivante dans le répertoire contenant l'exemple de code :

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Node.js compatible afin d'exécuter votre fonction.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Python compatible afin d'exécuter votre fonction.

Go 

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Go compatible afin d'exécuter votre fonction.

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

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Java compatible afin d'exécuter votre fonction.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Ruby compatible afin d'exécuter votre fonction.

où YOUR_TRIGGER_BUCKET_NAME est le nom du bucket Cloud Storage qui déclenche la fonction.

Finalisation de l'objet : déclencher la fonction

Pour déclencher la fonction :

  1. Créez un fichier gcf-test.txt vide dans le répertoire où se trouve l'exemple de code.

  2. Importez le fichier dans Cloud Storage afin de déclencher la fonction :

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

    où YOUR_TRIGGER_BUCKET_NAME est le nom de votre bucket Cloud Storage dans lequel vous importerez un fichier de test.

  3. Vérifiez les journaux pour vous assurer que les exécutions sont terminées :

    gcloud functions logs read --limit 50

Suppression de l'objet

Les événements de suppression d'objet sont déclenchés lorsqu'un objet est supprimé de façon réversible. Cela se produit lorsqu'un objet est écrasé ou supprimé dans un bucket pour lequel la gestion des versions des objets n'est pas activée. Si vous supprimez un objet en spécifiant son numéro de génération, sa suppression est également réversible.

Suppression de l'objet : déployer la fonction

En utilisant le même exemple de code que dans l'exemple de finalisation, déployez la fonction avec l'objet "delete" comme événement déclencheur. Exécutez la commande suivante dans le répertoire où se trouve l'exemple de code :

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Node.js compatible afin d'exécuter votre fonction.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Python compatible afin d'exécuter votre fonction.

Go 

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Go compatible afin d'exécuter votre fonction.

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

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Java compatible afin d'exécuter votre fonction.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Ruby compatible afin d'exécuter votre fonction.

où YOUR_TRIGGER_BUCKET_NAME est le nom du bucket Cloud Storage qui déclenche la fonction.

Suppression de l'objet : déclencher la fonction

Pour déclencher la fonction :

  1. Créez un fichier gcf-test.txt vide dans le répertoire où se trouve l'exemple de code.

  2. Assurez-vous que votre bucket est un bucket sans gestion des versions :

    gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

  3. Importez le fichier dans Cloud Storage :

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

    où YOUR_TRIGGER_BUCKET_NAME est le nom de votre bucket Cloud Storage dans lequel vous importerez un fichier de test. À ce stade, la fonction ne doit pas encore être exécutée.

  4. Supprimez le fichier pour déclencher la fonction :

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

  5. Vérifiez les journaux pour vous assurer que les exécutions sont terminées :

    gcloud functions logs read --limit 50

Notez que l'exécution de la fonction peut prendre un certain temps.

Archivage de l'objet

Les événements d'archivage d'objets sont déclenchés lorsqu'une version active d'un objet devient obsolète. Cela se produit lorsqu'un objet est écrasé ou supprimé dans un bucket pour lequel la gestion des versions d'objets est activée.

Archivage de l'objet : déployer la fonction

En utilisant le même exemple de code que dans l'exemple de finalisation, déployez la fonction avec l'archivage de l'objet comme événement déclencheur. Exécutez la commande suivante dans le répertoire où se trouve l'exemple de code :

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Node.js compatible afin d'exécuter votre fonction.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Python compatible afin d'exécuter votre fonction.

Go 

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Go compatible afin d'exécuter votre fonction.

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

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Java compatible afin d'exécuter votre fonction.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Ruby compatible afin d'exécuter votre fonction.

où YOUR_TRIGGER_BUCKET_NAME est le nom du bucket Cloud Storage qui déclenche la fonction.

Archivage de l'objet : déclencher la fonction

Pour déclencher la fonction :

  1. Créez un fichier gcf-test.txt vide dans le répertoire où se trouve l'exemple de code.

  2. Assurez-vous que la gestion des versions est activée dans votre bucket :

    gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --versioning

  3. Importez le fichier dans Cloud Storage :

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

    où YOUR_TRIGGER_BUCKET_NAME est le nom de votre bucket Cloud Storage dans lequel vous importerez un fichier de test. À ce stade, la fonction ne doit pas encore être exécutée.

  4. Archivez le fichier pour déclencher la fonction :

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

  5. Consultez les journaux pour vous assurer que les exécutions sont terminées :

    gcloud functions logs read --limit 50

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

Les événements de mise à jour des métadonnées sont déclenchés lorsque les métadonnées d'un objet existant sont mises à jour.

Mise à jour des métadonnées de l'objet : déployer la fonction

En utilisant le même exemple de code que dans l'exemple de finalisation, déployez la fonction avec la mise à jour des métadonnées en tant qu'événement déclencheur. Exécutez la commande suivante dans le répertoire où se trouve l'exemple de code :

Node.js 

gcloud functions deploy helloGCS \
--runtime nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Node.js compatible afin d'exécuter votre fonction.

Python 

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Python compatible afin d'exécuter votre fonction.

Go 

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Go compatible afin d'exécuter votre fonction.

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

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Java compatible afin d'exécuter votre fonction.

Ruby 

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

Utilisez le flag --runtime pour spécifier l'ID d'environnement d'exécution d'une version Ruby compatible afin d'exécuter votre fonction.

où YOUR_TRIGGER_BUCKET_NAME est le nom du bucket Cloud Storage qui déclenche la fonction.

Mise à jour des métadonnées de l'objet : déclencher la fonction

Pour déclencher la fonction :

  1. Créez un fichier gcf-test.txt vide dans le répertoire où se trouve l'exemple de code.

  2. Assurez-vous que votre bucket est un bucket sans gestion des versions :

    gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

  3. Importez le fichier dans Cloud Storage :

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

    où YOUR_TRIGGER_BUCKET_NAME est le nom de votre bucket Cloud Storage dans lequel vous importerez un fichier de test. À ce stade, la fonction ne doit pas encore être exécutée.

  4. Mettez à jour les métadonnées du fichier :

    gcloud storage objects update gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt --content-type=text/plain

  5. Consultez les journaux pour vous assurer que les exécutions sont terminées :

    gcloud functions logs read --limit 50