Fonctions d'arrière-plan

Les fonctions d'arrière-plan vous permettent d'appeler indirectement une fonction Cloud en réponse à un événement, tel qu'un message sur un sujet Pub/Sub, une modification dans un bucket Cloud Storage ou un événement Firebase.

Pour en savoir plus sur le traitement des nouvelles tentatives de fonction d'arrière-plan, consultez la section Répétition des tentatives des fonctions d'arrière-plan.

Environnements d'exécution acceptés

Les environnements d'exécution suivants sont compatibles avec les fonctions d'arrière-plan :

Langue	Versions
Node.js	All
Python	All
Go	All
Java	All

Remarque : Si vous écrivez une fonction basée sur des événements pour un environnement d'exécution qui n'est pas répertorié ci-dessus, veuillez consulter la page Fonctions CloudEvent.

Exemple d'utilisation

Les exemples ci-dessous montrent comment traiter les événements provenant de Pub/Sub et de Cloud Storage. Pour en savoir plus sur la gestion des événements provenant de différentes sources, consultez la page Appeler les fonctions Cloud.

Exemple Pub/Sub

Cet exemple montre une fonction cloud déclenchée par des événements Pub/Sub. Chaque fois qu'un message est publié dans un sujet Pub/Sub, la fonction est appelée et un message d'accueil contenant les données issues du message est écrit dans le journal.

Node.js

functions/helloworld/index.js

Afficher sur GitHub Commentaires

/**
 * Background Cloud Function to be triggered by Pub/Sub.
 * This function is exported by index.js, and executed when
 * the trigger topic receives a message.
 *
 * @param {object} message The Pub/Sub message.
 * @param {object} context The event metadata.
 */
exports.helloPubSub = (message, context) => {
  const name = message.data
    ? Buffer.from(message.data, 'base64').toString()
    : 'World';

  console.log(`Hello, ${name}!`);
};

Python

functions/helloworld/main.py

Afficher sur GitHub Commentaires

def hello_pubsub(event, context):
    """Background Cloud Function to be triggered by Pub/Sub.
    Args:
         event (dict):  The dictionary with data specific to this type of
         event. The `data` field contains the PubsubMessage message. The
         `attributes` field will contain custom attributes if there are any.
         context (google.cloud.functions.Context): The Cloud Functions event
         metadata. The `event_id` field contains the Pub/Sub message ID. The
         `timestamp` field contains the publish time.
    """
    import base64

    print("""This Function was triggered by messageId {} published at {}
    """.format(context.event_id, context.timestamp))

    if 'data' in event:
        name = base64.b64decode(event['data']).decode('utf-8')
    else:
        name = 'World'
    print('Hello {}!'.format(name))

Go

functions/helloworld/hello_pubsub.go

Afficher sur GitHub Commentaires

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Data []byte `json:"data"`
}

// HelloPubSub consumes a Pub/Sub message.
func HelloPubSub(ctx context.Context, m PubSubMessage) error {
	name := string(m.Data) // Automatically decoded from base64.
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

Java

functions/helloworld/hello-pubsub/src/main/java/functions/HelloPubSub.java

Afficher sur GitHub Commentaires

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.PubSubMessage;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Level;
import java.util.logging.Logger;

public class HelloPubSub implements BackgroundFunction<PubSubMessage> {
  private static final Logger logger = Logger.getLogger(HelloPubSub.class.getName());

  @Override
  public void accept(PubSubMessage message, Context context) {
    String name = "world";
    if (message != null && message.getData() != null) {
      name = new String(
          Base64.getDecoder().decode(message.getData().getBytes(StandardCharsets.UTF_8)),
          StandardCharsets.UTF_8);
    }
    logger.info(String.format("Hello %s!", name));
    return;
  }
}

C#

functions/helloworld/HelloPubSub/Function.cs

Afficher sur GitHub Commentaires

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

namespace HelloPubSub
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;

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

        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/pubsub/app.rb

Afficher sur GitHub Commentaires

require "functions_framework"
require "base64"

FunctionsFramework.cloud_event "hello_pubsub" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  name = Base64.decode64 event.data["message"]["data"] rescue "World"

  # A cloud_event function does not return a response, but you can log messages
  # or cause side effects such as sending additional events.
  logger.info "Hello, #{name}!"
end

Pour plus d'informations sur le déploiement de fonctions Cloud déclenchées par des événements Pub/Sub, consultez les pages Déclencheurs Pub/Sub et Tutoriel sur Pub/Sub.

Exemple Cloud Storage

Cet exemple décrit une fonction cloud déclenchée par des événements Cloud Storage. Chaque fois qu'un objet est créé dans un bucket Cloud Storage, la fonction est appelée et un message concernant la modification est écrit dans le journal.

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

Ruby

functions/helloworld/storage/app.rb

Afficher sur GitHub Commentaires

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # 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 en savoir plus sur le déploiement des fonctions Cloud déclenchées par des événements Cloud Storage, consultez les pages Déclencheurs Cloud Storage et Tutoriel sur Cloud Storage.

Paramètres de fonction

Les fonctions d'arrière-plan consistent à transmettre des arguments contenant les données associées à l'événement qui a déclenché l'exécution de la fonction. Les paramètres des fonctions d'arrière-plan sont décrits ci-dessous :

Node.js

Dans les environnements d'exécution Node.js, votre fonction reçoit les arguments (data, context, callback) :

Propriété	Description	Type
data	L'objet de données pour l'événement. Son type dépend de l'événement.	Objet
context	L'objet de contexte pour l'événement.	Objet
context.eventId	Un ID unique pour l'événement. Exemple : "70172329041928".	Chaîne
context.timestamp	La date/heure de création de cet événement. Par exemple, "2018-04-09T07:56:12.975Z".	Chaîne (ISO 8601)
context.eventType	Le type d'événement. Par exemple, "google.pubsub.topic.publish".	Chaîne
context.resource	La ressource qui a émis l'événement.	Objet
callback	Un rappel pour signaler l'achèvement de l'exécution de la fonction, suivi de la convention "errback", qui interprète le premier argument comme une erreur : callback(); // Success callback(null, 'Success!'); // Success callback(1); // Error callback(new Error('Failed')); // Error	Fonction

Python

Dans l'environnement d'exécution Python, votre fonction reçoit les arguments (data, context) :

Propriété	Description	Type
data	Un dictionnaire contenant les données de l'événement. Son format dépend de l'événement.	Objet Cloud Storage ou PubsubMessage
context	L'objet de contexte pour l'événement.	Contexte
context.event_id	Un ID unique pour l'événement. Exemple : "70172329041928".	Chaîne
context.timestamp	La date/heure de création de cet événement. Par exemple, "2018-04-09T07:56:12.975Z".	Chaîne (ISO 8601)
context.event_type	Le type d'événement. Par exemple, "google.pubsub.topic.publish".	Chaîne
context.resource	La ressource qui a émis l'événement.	Chaîne

Go

Dans l'environnement d'exécution Go, votre fonction reçoit les arguments (ctx, Event) :

Propriété	Description	Type
ctx	Une valeur context.Context contenant des métadonnées associées à l'événement. Vous pouvez récupérer les métadonnées à l'aide du package cloud.google.com/go/functions/metadata.	context.Context
Event	Une valeur struct dont vous définissez le type et dont la charge utile de l'événement sera désérialisée à l'aide de json.Unmarshal(). La charge utile de l'événement dépend du déclencheur pour lequel la fonction a été enregistrée. La définition de struct que vous fournissez dans votre code doit correspondre à la structure du type d'événement. La structure de chaque événement est documentée sur la page de déclencheur de l'événement correspondant. Notez que votre struct n'est pas obligatoire pour définir tous les champs contenus dans la charge utile. Vous ne souhaitez peut-être utiliser que certains champs de votre fonction. Dans ce cas, il vous suffit de définir ces champs dans votre struct. Vous pouvez également renommer un champ (par exemple, lorsque le nom du champ JSON contient un trait de soulignement) à l'aide de balises JSON sur ce champ.	Valeur struct personnalisée

Java

Dans l'environnement d'exécution Java, votre fonction reçoit les paramètres (event, context). Il existe deux types de fonctions d'arrière-plan, BackgroundFunction<T> et RawBackgroundFunction :

Propriété	Description	Type
event	Charge utile de l'événement. Le contenu de la charge utile dépend du déclencheur pour lequel la fonction a été enregistrée. Pour BackgroundFunction<T>, ce paramètre est de type T, une classe définie par l'utilisateur. La charge utile JSON de l'événement est désérialisée dans une instance de cette classe à l'aide de la méthode Gson.fromJson. Pour RawBackgroundFunction, ce paramètre est de type String et contient la charge utile JSON de l'événement.	Défini par l'utilisateur, ou String
context	Un objet Context en lecture seule contenant des métadonnées associées à l'événement.	Context

C#

Dans l'environnement d'exécution .NET Core 3.1, il existe deux types de fonctions CloudEvent : ICloudEvent<T> et ICloudEvent (également appelée fonction CloudEvent non typée).

Si vous mettez en œuvre ICloudEvent<T>, votre fonction reçoit les paramètres (cloudEvent, data, cancellationToken). Si vous mettez en œuvre ICloudEvent, votre fonction reçoit les paramètres (cloudEvent, cancellationToken).

Propriété	Description
cloudEvent	Événement CloudEvent qui a déclenché la fonction, contenant des métadonnées sur l'événement ainsi que les données brutes.
data	Données extraites de l'événement, de type T, où T est l'argument de type de votre fonction. Ce paramètre n'est pas intégré pour les fonctions CloudEvent non typées.
cancellationToken	Jeton d'annulation à surveiller pour la requête en cours d'annulation.

Ruby

Dans l'environnement d'exécution Ruby, les fonctions CloudEvent transmettent un seul paramètre, un objet CloudEvent de type CloudEvents::Event::V1. Les propriétés de cet objet incluent:

Valeur	Description	Type
id	Un ID unique pour l'événement. Exemple : 70172329041928.	String
time	La date/heure de création de cet événement.	DateTime
type	Le type d'événement. Exemple : google.cloud.pubsub.topic.v1.messagePublished.	String
source	La ressource qui a émis l'événement. Exemple : //pubsub.googleapis.com/projects/sample-project/topics/gcf-test.	URI
data	L'objet de données pour l'événement. Il s'agit d'un hachage dont les clés dépendent de l'événement.	Hash

Les données d'événement dépendent du déclencheur pour lequel la fonction a été enregistrée, par exemple, Pub/Sub ou Cloud Storage. Dans le cas de fonctions à déclenchement direct (par la commande gcloud functions call), les données d'événement contiennent le message que vous avez envoyé directement.

Remarque : Les données d'événement ne sont pas consignées automatiquement, car elles peuvent contenir des informations confidentielles que les utilisateurs ne souhaitent pas écrire dans Cloud Logging. Si vous souhaitez consigner les données d'événement, vous devez le faire explicitement, comme décrit sur la page Écrire, afficher des journaux et y répondre.

Arrêter les fonctions d'arrière-plan

Si une fonction crée des tâches en arrière-plan (telles que des threads, des futurs, des promesses, des rappels ou des processus système), vous devez arrêter ou résoudre ces tâches avant d'en finir avec la fonction. Les tâches qui ne sont pas arrêtées avant la fin d'une exécution particulière peuvent ne pas se terminer et peuvent également entraîner un comportement non défini.

Les environnements d'exécution Node.js permettent aux fonctions de fournir des références aux tâches en cours et de demander à Cloud Functions de les attendre. Pour ce faire, Cloud Functions peut procéder de l'une des deux manières suivantes :

• Il peut renvoyer une promesse (Promise) qui est résolue une fois la fonction terminée.
• Il peut appeler l'argument callback dans une fonction de rappel une fois l'opération terminée.

Étapes suivantes

• Déployer des fonctions Cloud Functions
• Appeler des fonctions du déclencheur Pub/Sub
• Appeler des fonctions du déclencheur Cloud Storage
• Tutoriel Cloud Functions avec Pub/Sub
• Tutoriel Cloud Functions avec Cloud Storage