Écrire des fonctions basées sur des événements

Dans les fonctions Cloud Run, vous utilisez des fonctions basées sur des événements lorsque vous souhaitez qu'une fonction soit appelée automatiquement en réponse à un événement qui se produit dans votre environnement cloud.

Il existe deux manières de mettre en œuvre des fonctions basées sur des événements. La manière de le faire dépend de l'environnement d'exécution du langage choisi :

Fonctions CloudEvent

Les fonctions CloudEvent sont basées sur CloudEvents, une spécification standard dans l'industrie pour la description des données d'événement de manière courante. Pour en savoir plus sur la spécification CloudEvents, consultez le dépôt GitHub de CloudEvents. Le projet CloudEvents fournit également un ensemble de SDK CloudEvents pour vous aider à utiliser des objets CloudEvents dans votre code.

L'exemple suivant montre un fichier source de fonction CloudEvent de base pour chaque environnement d'exécution. Consultez la section Structure du répertoire source pour savoir où trouver votre code source.

C# 

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the ICloudEventFunction<T> interface
    public class MyCloudEventFunction : ICloudEventFunction<CloudEventDataType>
    {
        // Implement the HandleAsync() method to handle CloudEvents
        public Task HandleAsync(CloudEvent cloudEvent, CloudEventDataType data, CancellationToken cancellationToken)
        {
            // Your code here
            // The data argument represents the CloudEvent data payload

            // Signal function completion
            return Task.CompletedTask;
        }
    }
}

Dans les environnements d'exécution .NET, vous utilisez le framework des fonctions pour .NET pour mettre en œuvre une classe de gestionnaire CloudEvent avec l'interface ICloudEventFunction<T>. La méthode HandleAsync() accepte un objet CloudEvent et la charge utile de données CloudEvent associée en tant qu'arguments.

Le type de l'argument de charge utile de données CloudEvent, affiché dans l'exemple ci-dessus en tant que CloudEventDataType, doit correspondre au type d'événement géré par la fonction. La bibliothèque .NET Google CloudEvents fournit des types de données pour les différents événements acceptés par Google.

Le point d'entrée de la fonction est le nom complet de la classe de gestionnaire CloudEvent, y compris l'espace de noms. Dans cet exemple, le point d'entrée est MyProject.MyCloudEventFunction.

Ruby 

require "functions_framework"

# Register a CloudEvent function with the Functions Framework
FunctionsFramework.cloud_event "my_cloudevent_function" do |cloud_event|
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data
end

Dans Ruby, vous enregistrez une fonction de gestionnaire CloudEvent avec le framework des fonctions pour Ruby. Votre fonction de gestionnaire doit accepter un objet Event CloudEvents en tant qu'argument.

Le point d'entrée de la fonction est le nom auprès duquel le gestionnaire est enregistré dans le framework des fonctions. Dans cet exemple, le point d'entrée est my_cloudevent_function.

PHP 

<?php

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

// Register a CloudEvent function with the Functions Framework
FunctionsFramework::cloudEvent('myCloudEventFunction', 'myCloudEventHandler');

// Define your CloudEvent handler
function myCloudEventHandler(CloudEventInterface $event): void
{
    // Your code here
    // Access the CloudEvent data payload via $event->getData()
}

En PHP, vous enregistrez une fonction de gestionnaire CloudEvent avec le framework des fonctions pour PHP. Votre fonction de gestionnaire doit accepter un argument conforme à l'interface CloudEventInterface.

Le point d'entrée de la fonction est le nom auprès duquel le gestionnaire est enregistré dans le framework des fonctions. Dans cet exemple, le point d'entrée est myCloudEventFunction.

Pour les fonctions CloudEvent, les données d'événement sont transmises à votre fonction au format CloudEvents, avec une charge utile de données CloudEvent correspondant au type d'événement qui déclenche votre fonction. Consultez la section Déclencheurs des fonctions Cloud Run pour plus d'informations sur les déclencheurs, les types d'événements et les formats de données d'événement acceptés.

Le dépôt Google Events contient des ressources permettant d'utiliser les événements Cloud émis par Google.

Fonctions d'arrière-plan

Les fonctions basées sur des événements dans les environnements d'exécution Node.js, Python, Go et Java attendent des arguments différents de ceux des fonctions CloudEvent. Ce plus ancien style de fonction basée sur des événements est appelé fonction d'arrière-plan.

L'exemple suivant montre un fichier source de fonction d'arrière-plan de base pour chaque environnement d'exécution. Consultez la section Structure du répertoire source pour savoir où trouver votre code source.

Node.js 

// Define and export an event handler
exports.myBackgroundFunction = (eventData, context, callback) => {
  // Your code here
  // The eventData argument represents the event data payload

  // Optionally signal function completion:
  callback();
};

Dans Node.js, vous définissez et exportez une fonction qui gère les données d'événement. Cloud Run Functions transmet à votre fonction de gestionnaire les arguments suivants :

  • eventData: objet représentant la charge utile des données d'événement. Son format dépend du type de l'événement.
  • context: objet contenant des métadonnées liées à l'événement.
  • callback: fonction facultative que vous pouvez appeler pour signaler la fin d'une exécution. Le premier argument de ce rappel est interprété comme signalant une erreur. Ne transmettez aucun argument ou un premier argument null pour signaler le succès.

Le point d'entrée de la fonction est le nom du gestionnaire d'événements exporté. Dans cet exemple, le point d'entrée est myBackgroundFunction.

Python 

# Define an event handler
def my_background_function(event_data, context):
  # Your code here
  # The event_data argument represents the event data payload

En Python, vous définissez une fonction qui gère les données d'événement. Cloud Run Functions transmet à votre fonction de gestionnaire les arguments suivants :

  • event_data: dictionnaire représentant la charge utile des données d'événement. Son format dépend du type de l'événement.
  • context: objet contenant des métadonnées liées à l'événement.

Le point d'entrée de la fonction est le nom de la fonction de gestionnaire. Dans cet exemple, le point d'entrée est my_background_function.

Go

package mybackgroundfunction

import (
    "context"
)

// Function MyBackgroundFunction accepts and handles event data
func MyBackgroundFunction(ctx context.Context, e EventDataType) error {
    // Your code here
    // The argument e represents the event data payload

    // Return nil if no error occurred
    return nil
}

En Go, vous définissez une fonction exportée qui gère les données d'événement. Cloud Run Functions transmet à votre fonction de gestionnaire les arguments suivants :

  • ctx: objet context.Context contenant des métadonnées sur l'événement. Vous pouvez récupérer les métadonnées à l'aide du package cloud.google.com/go/functions/metadata.
  • e: objet représentant la charge utile des données d'événement. Son type, illustré dans l'exemple ci-dessus en tant que EventDataType, doit être une structure correspondant au type d'événement géré par la fonction. La charge utile des données d'événement est désérialisée dans la structure à l'aide de json.Unmarshal().

Le point d'entrée de la fonction est le nom du gestionnaire d'événements exporté. Dans cet exemple, le point d'entrée est MyBackgroundFunction.

Java

package mybackgroundfunction;

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;

// Define a class that implements the BackgroundFunction<T> interface
public class MyBackgroundFunction implements BackgroundFunction<EventDataType> {
  // Implement the accept() method to handle events
  @Override
  public void accept(EventDataType eventData, Context context) {
    // Your code here
    // The eventData argument represents the event data payload
  }
}

En Java, vous utilisez l'API Java du framework des fonctions pour implémenter une classe de gestionnaire d'événements avec l'interface BackgroundFunction<T>. La méthode accept() accepte comme arguments la charge utile des données d'événement et un objet Context contenant des métadonnées sur l'événement.

Le type de l'argument de charge utile de données d'événement (affiché dans l'exemple ci-dessus en tant que EventDataType) doit correspondre au type d'événement géré par la fonction. La charge utile des données d'événement est désérialisée dans une instance de cette classe à l'aide de Gson.fromJson().

Le point d'entrée de la fonction est le nom complet de la classe de gestionnaire d'événements, y compris le nom du package. Dans cet exemple, le point d'entrée est mybackgroundfunction.MyBackgroundFunction.

Pour les fonctions d'arrière-plan, la charge utile de données d'événement est transmise directement à votre fonction dans un format correspondant au type d'événement qui déclenche votre fonction. Consultez Déclencheurs compatibles avec Cloud Run Functions (1re génération) pour en savoir plus sur les déclencheurs compatibles, les types d'événements et les formats de données d'événement associés.

Fonction terminée

Cloud Run Functions considère que l'exécution de la fonction basée sur des événements est terminée lorsque la fonction renvoie un résultat. Si la fonction crée des tâches en arrière-plan (par exemple, des threads, des futurs, des objets Promise JavaScript, des rappels ou des processus système), vous devez arrêter ou résoudre ces tâches avant d'en finir avec la fonction. Toute tâche qui n'est pas arrêtée avant le renvoi de la fonction peut ne pas être terminée et peut entraîner un comportement indéfini.

Nouvelles tentatives automatiques

Les fonctions basées sur des événements peuvent être configurées pour relancer automatiquement les appels ayant échoué. Pour en savoir plus, consultez la section Nouvelles tentatives d'exécution des fonctions basées sur des événements.

Étapes suivantes