Creare e gestire gli attivatori di eventi personalizzati

Con Cloud Functions (2nd gen), puoi attivare le funzioni in risposta a eventi personalizzati. Si tratta di eventi forniti da provider di eventi speciali o aggiuntivi, a differenza degli eventi Firebase supportati in modo nativo dall'SDK Firebase per Cloud Functions. Tramite gli attivatori di eventi personalizzati, la tua app può rispondere agli eventi forniti da Firebase Extensions oppure puoi pubblicare i tuoi eventi personalizzati e attivare funzioni in risposta.

Tutti gli eventi personalizzati sono conformi al formato evento JSON CloudEvents e vengono pubblicati su Eventarc. Eventarc Tariffe di utilizzo applicate.

Attivare funzioni con eventi personalizzati

Puoi pubblicare eventi personalizzati (o ottenere eventi dalle estensioni Firebase) e attivare funzioni in risposta a questi eventi implementando questo flusso di base:

  1. Pubblica gli eventi desiderati in un canale Eventarc o identifica gli eventi disponibili forniti da un'estensione che hai installato.
  2. Nel codice della funzione, iscriviti agli eventi sul canale Eventarc con un gestore di eventi.
  3. Nella funzione, analizza il payload restituito nell'oggetto CloudEvent ed esegui la logica personalizzata richiesta dalla tua app.

Ad esempio, un'app di gioco potrebbe voler inviare notifiche agli utenti quando entrano o escono dalla classifica dei primi dieci concorrenti. Questa app potrebbe pubblicare eventi della classifica nel canale predefinito e poi gestire l'evento in una funzione che invia notifiche push mirate agli utenti.

In un altro esempio, un'estensione progettata per aiutare le app a elaborare immagini di grandi dimensioni potrebbe generare un evento al termine del ridimensionamento dell'immagine. Le app con questa estensione installata potrebbero gestire l'evento di completamento aggiornando i link nell'app in modo che puntino a versioni ridimensionate dell'immagine.

Pubblicare un evento su un canale

Gli eventi Eventarc vengono pubblicati nei canali. I canali sono un modo per raggruppare gli eventi correlati e gestire le autorizzazioni di accesso. Quando installi un'estensione o esegui il deployment di una funzione che utilizza eventi personalizzati, Firebase crea automaticamente un canale predefinito denominato firebase nella regione us-central1. Firebase Admin SDK fornisce un pacchetto secondario eventarc per la pubblicazione sui canali.

Per pubblicare un evento da un server attendibile (o da un'altra funzione) utilizzando il canale predefinito:

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

Oltre a creare automaticamente il canale predefinito, Firebase imposta la variabile di ambiente EVENTARC_CLOUD_EVENT_SOURCE, che specifica l'origine dell'evento. Se pubblichi eventi al di fuori di Cloud Functions for Firebase, dovrai aggiungere esplicitamente il campo source nel payload dell'evento.

Gestire eventi personalizzati

Puoi gestire tutti gli eventi personalizzati, inclusi gli eventi delle estensioni, con i gestori onCustomEventPublished o on_custom_event_published. Innanzitutto, importa questo gestore dall'SDK Eventarc insieme a 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

Nel codice della funzione, trasmetti il nome dell'evento come mostrato per la funzione di esempio:

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

Per ogni estensione specifica, il payload restituito nell'oggetto evento fornisce dati che puoi utilizzare per eseguire una logica personalizzata per il flusso dell'applicazione. In questo caso, la funzione utilizza Admin SDK per copiare i metadati relativi all'immagine ridimensionata in una raccolta in Cloud Firestore, ottenendo il nome file da subject fornito dall'evento e salvando i metadati da data fornito dall'evento.

Pubblicare e gestire eventi su canali non predefiniti

I canali personalizzati possono essere utili nei casi in cui hai esigenze di autorizzazione speciali o altri requisiti e non vuoi lo stesso livello di visibilità e accesso per tutti gli eventi. Puoi creare i tuoi canali utilizzando la console Google Cloud. La pubblicazione e l'iscrizione agli eventi devono essere eseguite sullo stesso canale.

Nei casi in cui un evento personalizzato viene pubblicato su un canale non predefinito, devi specificare il canale nel codice della funzione. Ad esempio, se vuoi gestire gli eventi pubblicati in un canale non predefinito per la località us-west1, devi specificare il canale come mostrato di seguito:

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