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

ב-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 למטען הייעודי (payload) של האירוע.

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

אפשר לטפל בכל האירועים בהתאמה אישית, כולל אירועי תוספים, באמצעות ה-handlers‏ onCustomEventPublished או on_custom_event_published. קודם מייבאים את ה-handler הזה מ-Eventarc SDK יחד עם Firebase Admin SDK:

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

from firebase_admin import firestore, initialize_app
from firebase_functions import eventarc_fn
main.py

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

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

@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, צריך לציין את הערוץ באופן הבא:

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

@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