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 Firebase SDK 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 dans Eventarc. Eventarc Des frais d'utilisation 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 vouloir envoyer des notifications aux utilisateurs lorsqu'ils entrent dans le classement des dix meilleurs concurrents ou lorsqu'ils 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 de l'image. Les applications sur lesquelles cette extension est installée peuvent gérer l'événement de fin en mettant à jour les liens de 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. Le Firebase Admin SDK fournit un eventarc sous-package 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 devez 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 onCustomEventPublished ou on_custom_event_published gestionnaires. Commencez par importer ce gestionnaire à partir du SDK Eventarc avec le Firebase Admin SDK :

Node.js

const {onCustomEventPublished} = require("firebase-functions/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 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 le flux de votre application. Dans ce cas, la fonction utilise le 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 du subject fourni par l'événement et en enregistrant les métadonnées à partir des data fournies par l'événement.

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

Les canaux personnalisés peuvent être utiles lorsque vous avez des besoins d'autorisation spéciaux 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 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 un canal non 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 par défaut pour l' us-west1 emplacement, 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