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

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

כל האירועים בהתאמה אישית תואמים לפורמט JSON של אירועי CloudEvents ומפורסמים ב-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 הזה מ-SDK של Eventarc יחד עם 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