יצירת טריגרים של אירועים מותאמים אישית וטיפול בהם

באמצעות Cloud Functions (דור שני), אפשר להפעיל פונקציות בתגובה לאירועים מותאמים אישית. אלה אירועים שסופקו על ידי ספקי אירועים מיוחדים או נוספים, בניגוד לאירועי Firebase שנתמכים באופן מקורי על ידי ה-SDK של Firebase ל-Cloud Functions. באמצעות טריגרים של אירועים מותאמים אישית, האפליקציה יכולה להגיב לאירועים שסופקו על ידי Firebase Extensions, או שתוכלו לפרסם אירועים מותאמים אישית משלכם ולהפעיל פונקציות בתגובה להם.

כל האירועים בהתאמה אישית תואמים לפורמט האירועים של CloudEvents ב-JSON, ופורסמים ב-Eventarc. Eventarc חיובים על שימוש.

הפעלת פונקציות באמצעות אירועים מותאמים אישית

כדי לפרסם אירועים מותאמים אישית (או לקבל אירועים מתוספים של Firebase) ולהפעיל פונקציות בתגובה לאירועים האלה, אפשר להטמיע את התהליך הבסיסי הזה:

  1. מפרסמים את האירועים הרצויים בערוץ Eventarc, או מזהים אירועים זמינים שמספק תוסף שהותקן.
  2. בקוד הפונקציה, נרשמים לאירועים בערוץ Eventarc באמצעות גורם מטפל באירועים.
  3. בפונקציה, מנתחים את המטען הייעודי (payload) שמוחזר באובייקט CloudEvent ומבצעים את הלוגיקה בהתאמה אישית שנדרשת לאפליקציה.

לדוגמה, יכול להיות שאפליקציית משחקים תרצה לשלוח התראות למשתמשים כשהם נכנסים או יוצאים מהלוח של עשרת המתחרים המובילים. האפליקציה הזו יכולה לפרסם אירועים של לוח מנהיגים בערוץ ברירת המחדל, ואז לטפל באירוע בפונקציה ששולחת התראות פוּש ממוקדות למשתמשים.

דוגמה נוספת: תוסף שנועד לעזור לאפליקציות לעבד תמונות גדולות עשוי לשלוח אירוע בסיום שינוי גודל התמונה. אפליקציות עם התוסף הזה מותקן יכולות לטפל באירוע השלמת ההמרה על ידי עדכון הקישורים באפליקציה כך שיצביעו לגרסאות של התמונה בגודל מתאים.

פרסום אירוע בערוץ

אירועי Eventarc מתפרסמים בערוצים. ערוצים הם דרך לקבץ אירועים קשורים ולנהל את הרשאות הגישה. כשמתקינים תוסף או פורסים פונקציה שמשתמשת באירועים מותאמים אישית, מערכת Firebase יוצרת באופן אוטומטי ערוץ ברירת מחדל בשם firebase באזור us-central1. ה-Firebase Admin SDK מספק חבילה משנית של eventarc לפרסום בערוצים.

כדי לפרסם אירוע משרת מהימן (או מפונקציה אחרת) באמצעות ערוץ ברירת המחדל:

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 מגדירה את משתנה הסביבה EVENTARC_CLOUD_EVENT_SOURCE, שמציין את המקור של האירוע. אם מפרסמים אירועים מחוץ ל-Cloud Functions for Firebase, צריך להוסיף את השדה source באופן מפורש לעומס הנתונים של האירוע.

טיפול באירועים מותאמים אישית

אפשר לטפל בכל האירועים בהתאמה אישית, כולל אירועי תוספים, באמצעות הטיפולנים onCustomEventPublished או on_custom_event_published. קודם כול, מייבאים את הטיפול הזה מ-Eventarc SDK יחד עם 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

בקוד הפונקציה, מעבירים את שם האירוע כמו שמוצג בפונקציה לדוגמה:

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

לכל תוסף ספציפי, עומס העבודה (payload) שמוחזר באובייקט האירוע מספק נתונים שאפשר להשתמש בהם כדי לבצע לוגיקה מותאמת אישית לתהליך האפליקציה. במקרה הזה, הפונקציה משתמשת ב-Admin SDK כדי להעתיק מטא-נתונים לגבי התמונה ששונתה לגודל אחר לאוסף ב-Cloud Firestore, לקבל את שם הקובץ מה-subject שסופק על ידי האירוע ולשמור את המטא-נתונים מה-data שסופק על ידי האירוע.

פרסום אירועים בערוצים שאינם ערוצי ברירת המחדל וטיפול בהם

ערוצים מותאמים אישית יכולים להיות שימושיים במקרים שבהם יש לכם צורך בהרשאות מיוחדות או דרישות אחרות, ואתם לא רוצים שתהיה לכל האירועים אותה רמת חשיפה וגישה. אפשר ליצור ערוצים משלכם באמצעות מסוף Google Cloud. פרסום אירועים והרשמה אליהם צריכים להתבצע באותו ערוץ.

במקרים שבהם אירוע מותאם אישית מתפרסם בערוץ שאינו ערוץ ברירת המחדל, צריך לציין את הערוץ בקוד הפונקציה. לדוגמה, אם רוצים לטפל באירועים שפורסמו בערוץ שאינו ערוץ ברירת המחדל של המיקום us-west1, צריך לציין את הערוץ באופן הבא:

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