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.

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

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

/**
 * 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) => {
  if (file.resourceState === 'not_exists') {
    console.log(`File ${file.name} deleted.`);
  } else if (file.metageneration === '1') {
    // metageneration attribute is updated on metadata changes.
    // on create value is 1
    console.log(`File ${file.name} uploaded.`);
  } else {
    console.log(`File ${file.name} metadata updated.`);
  }
};

Python

functions/helloworld/main.py

Afficher sur GitHub Commentaires

def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
    Args:
         event (dict): The dictionary with data specific to this type of event.
         context (google.cloud.functions.Context): The Cloud Functions
         event metadata.
    """
    print("File: {}.".format(event['objectId']))

Go

functions/helloworld/hello_cloud_storage.go

Afficher sur GitHub Commentaires

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

import (
	"context"
	"log"
	"time"
)

// 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 {
	if e.ResourceState == "not_exists" {
		log.Printf("File %v deleted.", e.Name)
		return nil
	}
	if e.Metageneration == "1" {
		// The metageneration attribute is updated on metadata changes.
		// The on create value is 1.
		log.Printf("File %v created.", e.Name)
		return nil
	}
	log.Printf("File %v metadata updated.", e.Name)
	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) {
    if ("google.storage.object.finalize".equals(context.eventType())) {
      // Default event type for GCS-triggered functions
      logger.info(String.format("File %s uploaded.", event.getName()));
    } else {
      logger.warning(String.format("Unsupported event type: %s", context.eventType()));
    }
  }
}

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

Valeur	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) :

Valeur	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

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