Benutzerdefinierte Ereignistrigger erstellen und verarbeiten

Mit Cloud Functions (2. Generation) können Sie Funktionen als Reaktion auf benutzerdefinierte Ereignisse auslösen. Diese Ereignisse werden von speziellen oder zusätzlichen Ereignisanbietern im Gegensatz zu den Firebase-Ereignissen bereitgestellt, die vom Firebase SDK für Cloud Functions nativ unterstützt werden. Über benutzerdefinierte Ereignistrigger kann Ihre App auf von Firebase Extensions bereitgestellte Ereignisse reagieren. Sie können auch eigene benutzerdefinierte Ereignisse veröffentlichen und Funktionen als Reaktion darauf auslösen.

Alle benutzerdefinierten Ereignisse entsprechen dem JSON-Ereignisformat von CloudEvents und werden in Eventarc veröffentlicht. Für die Nutzung von Eventarc fallen Gebühren an.

Funktionen mit benutzerdefinierten Ereignissen auslösen

Sie können benutzerdefinierte Ereignisse veröffentlichen (oder Ereignisse von Firebase-Erweiterungen abrufen) und Funktionen als Reaktion auf diese Ereignisse auslösen. Dazu müssen Sie diesen grundlegenden Ablauf implementieren:

  1. Veröffentlichen Sie die gewünschten Ereignisse in einem Eventarc-Kanal oder suchen Sie nach verfügbaren Ereignissen, die von einer von Ihnen installierten Erweiterung bereitgestellt werden.
  2. Abonnieren Sie in Ihrem Funktionscode Ereignisse im Eventarc-Kanal mit einem Event-Handler.
  3. In der Funktion wird die im CloudEvent-Objekt zurückgegebene Nutzlast geparst und die benutzerdefinierte Logik ausgeführt, die für Ihre App erforderlich ist.

So können Sie beispielsweise in einer Spiele-App Benachrichtigungen an Nutzer senden, wenn sie die Bestenliste der Top 10 betreten oder verlassen. Diese App könnte Bestenlistenereignisse auf dem Standardkanal veröffentlichen und das Ereignis dann in einer Funktion verarbeiten, die gezielte Push-Benachrichtigungen an Nutzer sendet.

In einem anderen Beispiel kann eine Erweiterung, die Apps bei der Verarbeitung großer Bilder unterstützt, ein Ereignis ausgeben, wenn die Bildgröße angepasst wurde. Apps mit dieser Erweiterung können das Ereignis „Abschluss“ verarbeiten, indem sie Links in der App so aktualisieren, dass sie auf Versionen des Bildes mit angepasster Größe verweisen.

Ereignisse in einem Kanal veröffentlichen

Eventarc-Ereignisse werden in Channels veröffentlicht. Mit Channels können Sie ähnliche Ereignisse gruppieren und Zugriffsberechtigungen verwalten. Wenn Sie eine Erweiterung installieren oder eine Funktion bereitstellen, die benutzerdefinierte Ereignisse nutzt, erstellt Firebase automatisch einen Standardkanal namens firebase in der Region us-central1. Firebase Admin SDK stellt ein eventarc-Teilpaket für die Veröffentlichung in Kanälen bereit.

So veröffentlichen Sie ein Ereignis von einem vertrauenswürdigen Server (oder einer anderen Funktion) mithilfe des Standardkanals:

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

Firebase erstellt nicht nur automatisch den Standardkanal, sondern legt auch die Umgebungsvariable EVENTARC_CLOUD_EVENT_SOURCE fest, die die Quelle des Ereignisses angibt. Wenn Sie Ereignisse außerhalb von Cloud Functions for Firebase veröffentlichen, müssen Sie das Feld source in Ihrer Ereignisnutzlast explizit hinzufügen.

Benutzerdefinierte Ereignisse verarbeiten

Sie können alle benutzerdefinierten Ereignisse, einschließlich Erweiterungsereignisse, mit den Handlern onCustomEventPublished oder on_custom_event_published verarbeiten. Importieren Sie zuerst diesen Handler zusammen mit dem Firebase Admin SDK aus dem Eventarc 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

Geben Sie in Ihrem Funktionscode den Ereignisnamen wie in der Beispielfunktion gezeigt ein:

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

Für jede bestimmte Erweiterung liefert die im Ereignisobjekt zurückgegebene Nutzlast Daten, mit denen Sie eine benutzerdefinierte Logik für den Anwendungsfluss ausführen können. In diesem Fall verwendet die Funktion Admin SDK, um Metadaten zum Bild mit der geänderten Größe in eine Sammlung in Cloud Firestore zu kopieren. Dabei wird der Dateiname aus dem vom Ereignis bereitgestellten subject abgerufen und Metadaten aus dem vom Ereignis bereitgestellten data gespeichert.

Ereignisse auf nicht standardmäßigen Kanälen veröffentlichen und verarbeiten

Benutzerdefinierte Channels können nützlich sein, wenn Sie spezielle Berechtigungen oder andere Anforderungen haben und nicht für alle Ereignisse dieselbe Sichtbarkeit und Zugriffsberechtigungen benötigen. Sie können eigene Channels mit der Google Cloud Console erstellen. Ereignisse müssen auf demselben Kanal veröffentlicht und abonniert werden.

Wenn ein benutzerdefiniertes Ereignis auf einem anderen Kanal als dem Standardkanal veröffentlicht wird, müssen Sie den Kanal in Ihrem Funktionscode angeben. Wenn Sie beispielsweise Ereignisse verarbeiten möchten, die für den Standort us-west1 in einem anderen als dem Standardkanal veröffentlicht werden, müssen Sie den Kanal so angeben:

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