Créer et gérer des déclencheurs d'événements personnalisés

Avec Cloud Functions (2e génération), vous pouvez déclencher des fonctions en réponse à des événements personnalisés. Il s'agit d'événements fournis par des fournisseurs d'événements spéciaux ou supplémentaires, par opposition aux événements Firebase compatibles en mode natif avec le SDK Firebase pour Cloud Functions. Grâce aux déclencheurs d'événements personnalisés, votre application peut répondre aux événements fournis par Firebase Extensions. Vous pouvez également publier vos propres événements personnalisés et déclencher des fonctions en réponse à ceux-ci.

Tous les événements personnalisés sont conformes au format d'événement JSON CloudEvents et sont publiés sur Eventarc. Des frais d'utilisation Eventarc s'appliquent.

Déclencher des fonctions avec des événements personnalisés

Vous pouvez publier des événements personnalisés (ou obtenir des événements à partir d'extensions Firebase) et déclencher des fonctions en réponse à ces événements en implémentant ce flux de base :

  1. Publiez les événements souhaités sur un canal Eventarc ou identifiez les événements disponibles fournis par une extension que vous avez installée.
  2. Dans le code de votre fonction, abonnez-vous aux événements sur le canal Eventarc avec un gestionnaire d'événements.
  3. Dans la fonction, analysez la charge utile renvoyée dans l'objet CloudEvent et exécutez la logique personnalisée requise par votre application.

Par exemple, une application de jeu peut souhaiter envoyer des notifications aux utilisateurs lorsqu'ils entrent dans le classement des dix meilleurs joueurs ou en sortent. Cette application peut publier des événements de classement sur le canal par défaut, puis gérer l'événement dans une fonction qui envoie des notifications push ciblées aux utilisateurs.

Dans un autre exemple, une extension conçue pour aider les applications à traiter des images volumineuses peut émettre un événement à la fin du redimensionnement d'une image. Les applications sur lesquelles cette extension est installée peuvent gérer l'événement d'achèvement en mettant à jour les liens dans l'application pour qu'ils pointent vers les versions redimensionnées de l'image.

Publier un événement sur un canal

Les événements Eventarc sont publiés dans des canaux. Les canaux permettent de regrouper des événements associés et de gérer les autorisations d'accès. Lorsque vous installez une extension ou déployez une fonction qui consomme des événements personnalisés, Firebase crée automatiquement un canal par défaut nommé firebase dans la région us-central1. Firebase Admin SDK fournit un sous-package eventarc pour la publication sur les canaux.

Pour publier un événement à partir d'un serveur de confiance (ou d'une autre fonction) à l'aide du canal par défaut :

import {getEventarc} from 'firebase-admin/eventarc';

getEventarc().channel().publish({
    type: 'achieved-leaderboard',
    subject: 'Welcome to the top 10',
    data: {
      message: 'You have achieved the nth position in our leaderboard!  To see . . .'
    }
});

En plus de créer automatiquement le canal par défaut, Firebase définit la variable d'environnement EVENTARC_CLOUD_EVENT_SOURCE, qui spécifie la source de l'événement. Si vous publiez des événements en dehors de Cloud Functions for Firebase, vous devrez ajouter explicitement le champ source dans la charge utile de votre événement.

Gérer les événements personnalisés

Vous pouvez gérer tous les événements personnalisés, y compris les événements d'extension, avec les gestionnaires onCustomEventPublished ou on_custom_event_published. Commencez par importer ce gestionnaire à partir du SDK Eventarc avec Firebase Admin SDK :

Node.js

const {onCustomEventPublished} = require("firebase-functions/v2/eventarc");
const logger = require("firebase-functions/logger");
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

index.js

Python

from firebase_admin import firestore, initialize_app
from firebase_functions import eventarc_fn
main.py

Dans le code de votre fonction, transmettez le nom de l'événement comme indiqué pour la fonction d'exemple :

Node.js

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, write resized image details into Firestore.
      return getFirestore()
          .collection("images")
          .doc(event.subject.replace("/", "_")) // original file path
          .set(event.data); // resized images paths and sizes
    });
index.js

Python

@eventarc_fn.on_custom_event_published(
    event_type="firebase.extensions.storage-resize-images.v1.complete")
def onimageresized(event: eventarc_fn.CloudEvent) -> None:
    print("Received image resize completed event: ", event.type)

    if not isinstance(event.subject, str):
        print("No 'subject' data.")
        return

    # For example, write resized image details into Firestore.
    firestore_client: google.cloud.firestore.Client = firestore.client()
    collection = firestore_client.collection("images")
    doc = collection.document(event.subject.replace("/", "_"))  # original file path
    doc.set(event.data)  # resized images paths and sizes
main.py

Pour chaque extension, la charge utile renvoyée dans l'objet d'événement fournit des données que vous pouvez utiliser pour effectuer une logique personnalisée pour le flux de votre application. Dans ce cas, la fonction utilise Admin SDK pour copier les métadonnées de l'image redimensionnée dans une collection de Cloud Firestore, en obtenant le nom de fichier à partir de subject fourni par l'événement et en enregistrant les métadonnées de data fourni par l'événement.

Publier et gérer des événements sur des canaux non définis par défaut

Les canaux personnalisés peuvent être utiles si vous avez des besoins spécifiques en termes d'autorisations ou d'autres exigences, et que vous ne souhaitez pas le même niveau de visibilité et d'accès pour tous les événements. Vous pouvez créer vos propres chaînes à l'aide de la console Google Cloud. La publication et l'abonnement aux événements doivent être effectués sur le même canal.

Dans les cas où un événement personnalisé est publié sur un canal non défini par défaut, vous devez spécifier le canal dans le code de votre fonction. Par exemple, si vous souhaitez gérer les événements publiés dans un canal non défini par défaut pour l'emplacement us-west1, vous devez spécifier le canal comme indiqué :

Node.js

import { onCustomEventPublished } from "firebase-functions/v2/eventarc";

export const func = onCustomEventPublished(
    {
      eventType: "firebase.extensions.storage-resize-images.v1.complete",
      channel: "locations/us-west1/channels/firebase",
      region: "us-west1",
    },
    (event) => { ... });

Python

@eventarc_fn.on_custom_event_published(
    event_type="firebase.extensions.storage-resize-images.v1.complete",
    channel="locations/us-west1/channels/firebase",
    region="us-west1")
def onimageresizedwest(event: eventarc_fn.CloudEvent) -> None:
    print("Received image resize completed event: ", event.type)
    # ...
main.py