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

باستخدام 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:

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

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