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

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

تتّبع جميع الأحداث المخصّصة تنسيق أحداث CloudEvents JSON ويتم نشرها على 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 معالِجات. أولاً، استورِد هذا المعالج من Eventarc SDK مع Firebase Admin SDK

Node.js

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

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

بالنسبة إلى كل إضافة معيّنة، توفّر الحمولة التي يتم إرجاعها في عنصر الحدث بيانات يمكنك استخدامها لتنفيذ منطق مخصّص لمسار تطبيقك. في هذه الحالة، تستخدم الدالة Admin SDK لنسخ البيانات الوصفية حول الصورة التي تم تغيير حجمها إلى مجموعة في Cloud Firestore، والحصول على اسم الملف من الـ subject الذي يوفّره الحدث، وحفظ البيانات الوصفية من الـdata الذي يوفّرها الحدث.

نشر الأحداث ومعالجتها على قنوات غير تلقائية

يمكن أن تكون القنوات المخصّصة مفيدة في الحالات التي تحتاج فيها إلى أذونات خاصة أو متطلبات أخرى، ولا تريد أن يكون مستوى الرؤية والوصول نفسه لجميع الأحداث. يمكنك إنشاء قنواتك الخاصة باستخدام الـ Google Cloud Console. يجب نشر الأحداث والاشتراك فيها على القناة نفسها.

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