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 nativement 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 les extensions Firebase, ou vous pouvez 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 CloudEvents JSON et sont publiés sur Eventarc . Des frais d'utilisation d'Eventarc s'appliquent.

Fonctions de déclenchement 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 votre code de 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 ou quittent le classement des dix principaux concurrents. Cette application pourrait 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 de l'image. Les applications avec cette extension installée pourraient gérer l'événement d'achèvement en mettant à jour les liens dans l'application pour pointer vers des versions redimensionnées de l'image.

Publier un événement sur une chaîne

Les événements Eventarc sont publiés dans des chaînes . 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 . Le SDK Firebase Admin fournit un sous-package eventarc pour la publication sur les canaux.

Pour publier un événement depuis un serveur de confiance (ou une autre fonction) en utilisant le 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 pour 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 . Tout d’abord, importez ce gestionnaire depuis le SDK Eventarc avec le SDK Firebase Admin :

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

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

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

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

@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 particulière, la charge utile renvoyée dans l'objet é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 le SDK Admin pour copier les métadonnées de l'image redimensionnée dans une collection dans Cloud Firestore, en obtenant le nom de fichier du subject fourni par l'événement et en enregistrant les métadonnées des data fournies par l'événement.

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

Les canaux personnalisés peuvent être utiles dans les cas où vous avez des besoins particuliers en matière d'autorisations ou d'autres exigences et 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 se faire sur la même chaîne.

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

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) => { ... });

@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