Creare e gestire gli attivatori di eventi personalizzati

Con Cloud Functions (2ª gen.), puoi attivare 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'Firebase SDK per Cloud Functions. Tramite i trigger di eventi personalizzati, la tua app può rispondere agli eventi forniti da Firebase Extensions, oppure puoi pubblicare i tuoi eventi personalizzati e attivare le funzioni in risposta a questi eventi.

Tutti gli eventi personalizzati sono conformi al formato evento JSON di CloudEvents e vengono pubblicati su Eventarc. Eventarc si applicano le tariffe di utilizzo.

Attivare le funzioni con eventi personalizzati

Puoi pubblicare eventi personalizzati (o ottenere eventi dalle estensioni Firebase) e attivare le 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, sottoscrivi gli 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 di 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 emettere un evento al completamento del ridimensionamento delle immagini. Le app con questa estensione installata potrebbero gestire l'evento di completamento aggiornando i link nell'app in modo che rimandino alle versioni ridimensionate dell'immagine.

Pubblicare un evento in 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. Il Firebase Admin SDK fornisce un eventarc sottopacchetto 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, devi aggiungere esplicitamente il campo source nel payload dell'evento.

Gestire gli eventi personalizzati

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

Nel codice della funzione, inserisci 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 i dati che puoi utilizzare per eseguire la logica personalizzata per il flusso dell'applicazione. In questo caso, la funzione utilizza l'SDK Admin per copiare i metadati relativi all'immagine ridimensionata in una raccolta in Cloud Firestore, ottenendo il nome file dal subject fornito dall'evento e salvando i metadati dai data forniti dall'evento.Admin SDK

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 la sottoscrizione degli 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