Tworzenie i obsługa reguł zdarzeń niestandardowych

Dzięki Cloud Functions (2. generacji) możesz wywoływać funkcje w odpowiedzi na niestandardowe zdarzenia. Są to zdarzenia dostarczane przez specjalnych lub dodatkowych dostawców zdarzeń, w przeciwieństwie do zdarzeń Firebase obsługiwanych natywnie przez pakiet Firebase SDK dla Cloud Functions. Dzięki regułom opartym na zdarzeniach niestandardowych Twoja aplikacja może reagować na zdarzenia dostarczane przez Firebase Extensions. Możesz też publikować własne zdarzenia niestandardowe i wywoływać funkcje w odpowiedzi na nie.

Wszystkie zdarzenia niestandardowe są zgodne z formatem zdarzeń JSON CloudEvents i są publikowane w Eventarc. Eventarc Obowiązują opłaty za korzystanie.

Wywoływanie funkcji za pomocą zdarzeń niestandardowych

Możesz publikować zdarzenia niestandardowe (lub uzyskiwać zdarzenia z rozszerzeń Firebase) i wywoływać funkcje w odpowiedzi na te zdarzenia, implementując ten podstawowy przepływ:

  1. Opublikuj żądane zdarzenia w kanale Eventarc lub zidentyfikuj dostępne zdarzenia dostarczane przez zainstalowane rozszerzenie.
  2. W kodzie funkcji zasubskrybuj zdarzenia w kanale Eventarc za pomocą procedury obsługi zdarzeń.
  3. W funkcji przeanalizuj ładunek zwrócony w obiekcie CloudEvent i wykonaj dowolną logikę niestandardową wymaganą przez aplikację.

Na przykład aplikacja do gier może wysyłać powiadomienia do użytkowników, gdy wchodzą oni do tabeli wyników 10 najlepszych graczy lub z niej wychodzą. Ta aplikacja może publikować zdarzenia tabeli wyników w kanale domyślnym, a następnie obsługiwać zdarzenie w funkcji, która wysyła do użytkowników ukierunkowane powiadomienia push.

W innym przykładzie rozszerzenie zaprojektowane, aby pomagać aplikacjom w przetwarzaniu dużych obrazów, może emitować zdarzenie po zakończeniu zmiany rozmiaru obrazu. Aplikacje z zainstalowanym tym rozszerzeniem mogą obsługiwać zdarzenie zakończenia, aktualizując linki w aplikacji, aby wskazywały na wersje obrazu o zmienionym rozmiarze.

Publikowanie zdarzenia w kanale

Zdarzenia Eventarc są publikowane w kanałach. Kanały umożliwiają grupowanie powiązanych zdarzeń i zarządzanie uprawnieniami dostępu. Gdy zainstalujesz rozszerzenie lub wdrożysz funkcję, która korzysta ze zdarzeń niestandardowych, Firebase automatycznie utworzy kanał domyślny o nazwie firebase w regionie us-central1. Firebase Admin SDK udostępnia podpakiet eventarc do publikowania w kanałach.

Aby opublikować zdarzenie z zaufanego serwera (lub innej funkcji) za pomocą kanału domyślnego:

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

Oprócz automatycznego tworzenia kanału domyślnego Firebase ustawia zmienną środowiskową EVENTARC_CLOUD_EVENT_SOURCE, która określa źródło zdarzenia. Jeśli publikujesz zdarzenia poza Cloud Functions for Firebase, musisz wyraźnie dodać pole source w ładunku zdarzenia.

Obsługa zdarzeń niestandardowych

Możesz obsługiwać wszystkie zdarzenia niestandardowe, w tym zdarzenia rozszerzeń, za pomocą procedur obsługi onCustomEventPublished lub on_custom_event_published. Najpierw zaimportuj tę procedurę obsługi z pakietu Eventarc SDK wraz z 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

W kodzie funkcji przekaż nazwę zdarzenia, jak pokazano w przypadku funkcji przykładowej:

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

W przypadku każdego rozszerzenia ładunek zwrócony w obiekcie zdarzenia zawiera dane, których możesz użyć do wykonania logiki niestandardowej w przepływie aplikacji. W tym przypadku funkcja używa pakietu Admin SDK do kopiowania metadanych o obrazie o zmienionym rozmiarze do kolekcji w Cloud Firestore, pobierając nazwę pliku z pola subject dostarczonego przez zdarzenie i zapisując metadane z pola data dostarczonego przez zdarzenie.

Publikowanie i obsługa zdarzeń w kanałach innych niż domyślne

Kanały niestandardowe mogą być przydatne w przypadkach, gdy masz specjalne potrzeby dotyczące uprawnień lub inne wymagania i nie chcesz, aby wszystkie zdarzenia miały ten sam poziom widoczności i dostępu. Możesz tworzyć własne kanały za pomocą konsoli Google Cloud. Publikowanie i subskrybowanie zdarzeń musi odbywać się w tym samym kanale.

W przypadkach, gdy zdarzenie niestandardowe jest publikowane w kanale innym niż domyślny, musisz określić kanał w kodzie funkcji. Jeśli na przykład chcesz obsługiwać zdarzenia publikowane w kanale innym niż domyślny w lokalizacji us-west1, musisz określić kanał w sposób pokazany poniżej:

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