إنشاء عوامل تشغيل الأحداث المخصّصة والتعامل معها

باستخدام Cloud Functions (الجيل الثاني)، يمكنك تشغيل الدوال استجابةً لأحداث مخصّصة. وهي أحداث يقدّمها موفّرو أحداث خاصّون أو إضافيون، على عكس أحداث Firebase المتوافقة أصلاً مع حزمة تطوير البرامج (SDK) الخاصة بـ Firebase في Cloud Functions. من خلال عوامل تشغيل الأحداث المخصّصة، يمكن لتطبيقك الاستجابة للأحداث التي توفّرها Firebase Extensions، أو يمكنك نشر أحداثك المخصّصة وتشغيل الدوال استجابةً لها.

تتّبع جميع الأحداث المخصّصة تنسيق أحداث JSON في CloudEvents ويتم نشرها إلى Eventarc. تسري Eventarc رسوم الاستخدام.

تشغيل الدوال باستخدام أحداث مخصّصة

يمكنك نشر أحداث مخصّصة (أو الحصول على أحداث من إضافات Firebase) وتشغيل الدوال استجابةً لهذه الأحداث من خلال تنفيذ هذا المسار الأساسي:

1. انشر الأحداث المطلوبة في قناة Eventarc، أو حدِّد الأحداث المتاحة التي يوفّرها أحد الإضافات التي ثبّتها.
2. في رمز الدالة، اشترِك في الأحداث على قناة Eventarc باستخدام معالج أحداث.
3. في الدالة، حلِّل الحمولة التي تم إرجاعها في عنصر 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. أولاً، استورِد هذا المعالج من حزمة تطوير البرامج (SDK) الخاصة بخدمة Eventarc مع 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

بالنسبة إلى كل إضافة معيّنة، توفّر الحمولة التي يتم عرضها في عنصر الحدث بيانات يمكنك استخدامها لتنفيذ منطق مخصّص لسير تطبيقك. في هذه الحالة، تستخدم الدالة 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