Tutoriel sur Cloud Storage

Ce tutoriel simple décrit comment rédiger, déployer et déclencher une fonction Cloud Functions d'arrière-plan avec un déclencheur Cloud Storage.

Objectifs

Coûts

Ce tutoriel fait appel à des composants facturables de Cloud Platform, en particulier :

  • Google Cloud Functions
  • Google Cloud Storage

Utilisez le simulateur de coût pour générer une estimation des coûts en fonction de votre utilisation prévue.

Les nouveaux utilisateurs de Cloud Platform peuvent bénéficier d'un essai gratuit.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder à la page de sélection du projet

  3. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

  4. Activer les API Cloud Functions, Cloud Build, and Cloud Storage.

    Activer les API

  5. Installez et initialisez le SDK Cloud.
  6. Mettez à jour les composants gcloud :
    gcloud components update
  7. Préparez votre environnement de développement :

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é :

    gsutil mb 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.

    C#

    git clone https://github.com/GoogleCloudPlatform/dotnet-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 qui contient l'exemple de code de Cloud 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/

    C#

    cd dotnet-docs-samples/functions/helloworld/HelloGcs/

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.
 *
 * @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.

    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


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

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#

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, exécutez la commande suivante dans le répertoire contenant l'exemple de code :

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

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 :

    gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
    

    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 particulièrement utiles pour les buckets sans gestion des versions. Ils sont déclenchés lorsqu'une ancienne version d'un objet est supprimée. Ils sont également déclenchés lorsqu'un objet est écrasé. Les déclencheurs de suppression d'objet peuvent également être utilisés avec des buckets avec gestion des versions, qui se déclenchent lorsqu'une version d'un objet est définitivement supprimée.

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 nodejs10 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
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.delete
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 HelloGCSInfo \
--runtime go111 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete
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 functions.HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

C#

gcloud functions deploy csharp-gcs-function \
--entry-point HelloGcs.Function \
--runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

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 :

    gsutil versioning set off gs://YOUR_TRIGGER_BUCKET_NAME
    
  3. Importez le fichier dans Cloud Storage :

    gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
    

    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 :

    gsutil 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 ne peuvent être utilisés qu'avec des buckets avec gestion des versions. Ils sont déclenchés lorsqu'une ancienne version d'un objet est archivée. Cela signifie en particulier que la suppression ou le remplacement d'un objet existant déclenche un événement d'archivage.

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 nodejs10 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
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.archive
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 HelloGCSInfo \
--runtime go111 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive
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 functions.HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

C#

gcloud functions deploy csharp-gcs-function \
--entry-point HelloGcs.Function \
--runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

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 :

    gsutil versioning set on gs://YOUR_TRIGGER_BUCKET_NAME
    
  3. Importez le fichier dans Cloud Storage :

    gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
    

    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 :

    gsutil 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 nodejs10 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
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.metadataUpdate
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 HelloGCSInfo \
--runtime go111 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate
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 functions.HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

C#

gcloud functions deploy csharp-gcs-function \
--entry-point HelloGcs.Function \
--runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

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 :

    gsutil versioning set off gs://YOUR_TRIGGER_BUCKET_NAME
    
  3. Importez le fichier dans Cloud Storage :

    gsutil cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME
    

    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 :

    gsutil -m setmeta -h "Content-Type:text/plain" 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
    

Effectuer un nettoyage

Afin d'éviter que des frais ne soient facturés sur votre compte Google Cloud Platform pour les ressources utilisées dans ce tutoriel, procédez comme suit :

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  1. Dans Cloud Console, accédez à la page Gérer les ressources.

    Accéder à la page Gérer les ressources

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer .
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Supprimer une fonction Cloud Functions

La suppression de fonctions Cloud Functions ne supprime pas les ressources stockées dans Cloud Storage.

Pour supprimer la fonction Cloud que vous avez créée dans ce tutoriel, exécutez la commande suivante :

Node.js

gcloud functions delete helloGCS 

Python

gcloud functions delete hello_gcs 

Go

gcloud functions delete HelloGCSInfo 

Java

gcloud functions delete java-gcs-function 

C#

gcloud functions delete csharp-gcs-function 

Vous pouvez également supprimer des fonctions Cloud Functions à partir de Google Cloud Console.