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

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

Python

from firebase_admin import firestore, initialize_app
from firebase_functions import eventarc_fn

في رمز الدالة، أدخِل اسم الحدث كما هو موضّح في دالة المثال:

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
    });

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

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