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 pris en charge en mode natif par le SDK Firebase pour Cloud Functions. Via des déclencheurs d'événements personnalisés, votre application peut répondre aux événements fournis par Firebase Extensions, ou vous pouvez publier vos propres événements personnalisés et déclencher des fonctions en réponse à eux.

Tous les événements personnalisés sont conformes au format d'événement JSON CloudEvents et sont publiés dans Eventarc. Des frais d'utilisation de 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 envoyer des notifications aux utilisateurs lorsqu'ils entrent ou quittent le classement des 10 meilleurs concurrents. 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 de grandes images peut émettre un événement à la fin du redimensionnement de l'image. Les applications avec cette extension installée peuvent gérer l'événement de finalisation en mettant à jour les liens de l'application pour qu'ils pointent vers des 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 approuvé (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 devez ajouter explicitement le champ source dans la charge utile de l'é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, ainsi que 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é dans l'exemple de fonction:

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 exécuter une logique personnalisée pour votre flux d'application. Dans ce cas, la fonction utilise Admin SDK pour copier les métadonnées de l'image redimensionnée dans une collection dans Cloud Firestore, obtenir le nom de fichier à partir de subject fourni par l'événement et enregistrer les métadonnées à partir de data fourni par l'événement.

Publier et gérer des événements sur des canaux autres que par défaut

Les canaux personnalisés peuvent être utiles si vous avez des besoins d'autorisation spéciaux ou d'autres exigences, et si 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 canaux à l'aide de la console Google Cloud. La publication et l'abonnement aux événements doivent être effectués sur le même canal.

Si un événement personnalisé est publié sur une chaîne autre que la chaîne par défaut, vous devez spécifier la chaîne dans le code de votre fonction. Par exemple, si vous souhaitez gérer les événements publiés dans un canal autre que le canal 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