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

עם 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 של ה-handlers שלו. קודם כול, מייבאים את ה-handler הזה מ-Eventarc SDK יחד עם Firebase Admin SDK:

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

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