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

Fonctions CloudEvent

Vous utilisez les fonctions CloudEvent pour appeler votre fonction.

Les CloudEvents 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.

Node.js 

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent function with the Functions Framework
functions.cloudEvent('myCloudEventFunction', cloudEvent => {
  // Your code here
  // Access the CloudEvent data payload via cloudEvent.data
});

Dans Node.js, vous enregistrez une fonction de gestionnaire CloudEvent avec le framework des fonctions pour Node.js. Votre fonction de gestionnaire doit accepter un objet CloudEvent comme 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 myCloudEventFunction.

Python 

import functions_framework

# Register a CloudEvent function with the Functions Framework
@functions_framework.cloud_event
def my_cloudevent_function(cloud_event):
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data

En Python, vous enregistrez une fonction de gestionnaire CloudEvent avec le framework des fonctions pour Python. Votre fonction de gestionnaire doit accepter un objet CloudEvent comme argument.

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

Go

package mycloudeventfunction

import (
    "context"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"
    "github.com/cloudevents/sdk-go/v2/event"
)

func init() {
    // Register a CloudEvent function with the Functions Framework
    functions.CloudEvent("MyCloudEventFunction", myCloudEventFunction)
}

// Function myCloudEventFunction accepts and handles a CloudEvent object
func myCloudEventFunction(ctx context.Context, e event.Event) error {
    // Your code here
    // Access the CloudEvent data payload via e.Data() or e.DataAs(...)

    // Returning an error causes its message to be logged.
    // Example:
    err := myInternalFunction() // may return an error
    if err != nil {
        // Append error message to log
        return err
    }

    // Return nil if no error occurred
    return nil
}

Dans Go, vous enregistrez une fonction de gestionnaire CloudEvent avec le framework des fonctions pour Go. Votre fonction de gestionnaire doit accepter un objet CloudEvents event.Event 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 MyCloudEventFunction.

Java

package mycloudeventfunction;

import com.google.cloud.functions.CloudEventsFunction;
import io.cloudevents.CloudEvent;

// Define a class that implements the CloudEventsFunction interface
public class MyCloudEventFunction implements CloudEventsFunction {
  // Implement the accept() method to handle CloudEvents
  @Override
  public void accept(CloudEvent event) {
    // Your code here
    // Access the CloudEvent data payload via event.getData()
    // To get the data payload as a JSON string, use:
    // new String(event.getData().toBytes())
  }
}

En Java, vous utilisez l'API Java du framework des fonctions pour mettre en œuvre une classe de gestionnaire CloudEvent avec l'interface CloudEventsFunction. La méthode accept() doit accepter un objet CloudEvent comme argument et effectuer tout traitement sur l'événement.

Le point d'entrée de la fonction est le nom complet de la classe de gestionnaire CloudEvent, y compris le nom du package. Dans cet exemple, le point d'entrée est mycloudeventfunction.MyCloudEventFunction.

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.

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