Fonctions CloudEvent

Une fonction CloudEvent est un type de fonction basée sur des événements. Les fonctions CloudEvent sont appelées indirectement en réponse à des événements, tels qu'un message sur un sujet Pub/Sub, une modification dans un bucket Cloud Storage ou un événement Firebase.

Les fonctions CloudEvent sont conceptuellement similaires aux fonctions d'arrière-plan. La principale différence entre les deux est que les fonctions CloudEvent utilisent un format d'événement standard dans l'industrie appelé CloudEvents. Une autre différence est que Cloud Functions appelle des fonctions CloudEvent à l'aide de requêtes HTTP, qui peuvent être reproduites ailleurs. Ces différences permettent de déplacer facilement les fonctions CloudEvent entre les plates-formes de calcul.

Environnements d'exécution acceptés

Les environnements d'exécution suivants sont compatibles avec les fonctions CloudEvent :

Langue Version(s)
PHP Beta All
C# Beta Toutes
Ruby Beta Toutes

Paramètres de fonction

Les fonctions CloudEvent transmettent un seul argument cloudEvent contenant les propriétés et les métadonnées associées à l'événement qui a déclenché l'exécution de la fonction. Les événements cloud entrants sont ensuite convertis dans les représentations spécifiques aux langages indiquées ci-dessous à l'aide des bibliothèques du framework des fonctions.

C#

Le paramètre cloudEvent est transmis à votre fonction en tant qu'objet CloudEvent qui contient les propriétés suivantes :

Valeur Type Description
Id String ID unique de l'événement.
Source Uri Entité Google Cloud affectée par l'événement, au format /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
Type String Type CloudEvent de l'événement reçu.
Time DateTimeOffset pouvant être nul Horodatage du moment où l'événement s'est produit.
SpecVersion CloudEventsSpecVersion Version de spécification CloudEvents utilisée pour créer l'événement.
Data Object Un objet (object) contenant des données spécifiques au type d'événements.
Subject String pouvant être nulle La valeur de "subject" dépend du type d'événement déclenché. Si l'événement sous-jacent fait référence à un objet Cloud Storage, cette propriété sera définie sur l'emplacement de l'objet, au format objects/path/to/object. Certains événements ne définissent pas de valeur pour "subject". Dans ce cas, cette propriété sera définie sur null.

Ruby

Le paramètre cloudEvent est transmis à votre fonction en tant qu'objet CloudEvents::Event::V1 qui contient les propriétés suivantes :

Valeur Type Description
cloudEvent.id String ID unique de l'événement.
cloudEvent.source URI Entité Google Cloud affectée par l'événement, au format /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent.type String Type CloudEvent de l'événement reçu.
cloudEvent.time DateTime Horodatage du moment où l'événement s'est produit.
cloudEvent.specversion String Version de spécification CloudEvents utilisée pour créer l'événement.
cloudEvent.data Hash Un objet (Hash) contenant des données spécifiques aux types d'événements.
cloudEvent.subject String ou Nil La valeur de "subject" dépend du type d'événement déclenché. Si l'événement sous-jacent fait référence à un objet Cloud Storage, cette propriété sera définie sur l'emplacement de l'objet, au format objects/path/to/object. Certains événements ne définissent pas de valeur pour "subject". Dans ce cas, cette propriété sera définie sur Nil.

PHP

Le paramètre cloudEvent est transmis à votre fonction en tant qu'objet CloudEvent, qui contient les éléments suivants :

Fonction Type Description
cloudEvent->getId() string ID unique de l'événement.
cloudEvent->getSource() string Entité Google Cloud affectée par l'événement, au format /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent->getType() string Type CloudEvent de l'événement reçu.
cloudEvent->getTime() ?string Horodatage du moment où l'événement s'est produit.
cloudEvent->getSpecVersion() string Version de spécification CloudEvents utilisée pour créer l'événement.
cloudEvent->getSubject() ?string La valeur de "subject" dépend du type d'événement déclenché. Si l'événement sous-jacent fait référence à un objet Cloud Storage, cette propriété sera définie sur l'emplacement de l'objet, au format objects/path/to/object. Certains événements ne définissent pas de valeur pour "subject". Dans ce cas, cette propriété sera définie sur null.
cloudEvent->getData() Object Un objet (object) contenant des données spécifiques au type d'événements.

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.

C#

functions/helloworld/HelloPubSub/Function.cs 
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 
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

PHP

functions/helloworld_pubsub/index.php 

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

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloworldPubsub', 'helloworldPubsub');

function helloworldPubsub(CloudEventInterface $event): void
{
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');

    $cloudEventData = $event->getData();
    $pubSubData = base64_decode($cloudEventData['message']['data']);

    $name = $pubSubData ? htmlspecialchars($pubSubData) : 'World';
    fwrite($log, "Hello, $name!" . PHP_EOL);
}

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

C#

functions/helloworld/HelloGcs/Function.cs 
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
{
     /// <summary>
     /// Example Cloud Storage-triggered function.
     /// This function can process any event from Cloud Storage.
     /// </summary>
    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 
require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # 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

PHP

functions/helloworld_storage/index.php 

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

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloGCS', 'helloGCS');

function helloGCS(CloudEventInterface $cloudevent)
{
    // This function supports all Cloud Storage event types.
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');
    $data = $cloudevent->getData();
    fwrite($log, 'Event: ' . $cloudevent->getId() . PHP_EOL);
    fwrite($log, 'Event Type: ' . $cloudevent->getType() . PHP_EOL);
    fwrite($log, 'Bucket: ' . $data['bucket'] . PHP_EOL);
    fwrite($log, 'File: ' . $data['name'] . PHP_EOL);
    fwrite($log, 'Metageneration: ' . $data['metageneration'] . PHP_EOL);
    fwrite($log, 'Created: ' . $data['timeCreated'] . PHP_EOL);
    fwrite($log, 'Updated: ' . $data['updated'] . PHP_EOL);
}

Pour en savoir plus sur le déploiement des fonctions CloudEvent déclenchées par des événements Cloud Storage, consultez les pages Déclencheurs Cloud Storage et Tutoriel sur Cloud Storage.

Pour en savoir plus sur la diffusion d'événements (également au format CloudEvents) à un service Cloud Run cible à l'aide d'Eventarc, consultez la page Créer un déclencheur pour Cloud Run.

Conseils et astuces

Journalisation des événements

Le contenu des événements n'est pas automatiquement consigné, car il peut contenir des informations confidentielles. Si vous souhaitez consigner le contenu des événements, vous devez le faire explicitement, comme décrit sur la pageÉcrire, afficher des journaux et y répondre.

Arrêter des fonctions CloudEvent

Si une fonction CloudEvent crée des tâches en arrière-plan, vous devez résoudre ces tâches avant de terminer la fonction pour éviter les erreurs et/ou un comportement indéfini.

Nouvelles tentatives automatiques

Les fonctions CloudEvent 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 déclenchées par des événements.

Étapes suivantes