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

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

ملاحظة: هذه الميزة متاحة للجميع. وهذا يعني أنّ الوظيفة قد تتغير بطرق غير متوافقة مع الإصدارات القديمة. لا يخضع إصدار المعاينة لأي سياسة إيقاف أو اتفاقية مستوى الخدمة، وقد يتم دعمه بشكل محدود أو لا يتم دعمه مطلقًا.

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

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

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

1. انشر الأحداث المطلوبة على قناة Eventarc أو حدِّد الأحداث المتاحة التي تقدّمها الإضافة التي ثبَّتها.
2. في رمز الدالة، اشترِك في الأحداث على قناة Eventarc باستخدام معالج الأحداث.
3. في الدالة، حلِّل الحمولة التي يتم عرضها في كائن CloudEvent ونفِّذ أي منطق مخصّص يتطلبه تطبيقك.

على سبيل المثال، قد يرغب تطبيق لعبة في إرسال إشعارات إلى المستخدمين عند دخولهم أو مغادرة قائمة الصدارة لأفضل عشرة منافسين. يمكن لهذا التطبيق نشر أحداث قوائم الصدارة في القناة التلقائية، ثم التعامل مع الحدث من خلال وظيفة ترسل إشعارات فورية مستهدفة إلى المستخدمين.

وفي مثال آخر، إنّ إضافة مُصمّمة لمساعدة التطبيقات في معالجة الصور الكبيرة قد تنبعث من حدث عند اكتمال تغيير حجم الصور. يمكن للتطبيقات التي تم تثبيت هذه الإضافة بها معالجة حدث الاكتمال من خلال تحديث الروابط في التطبيق للإشارة إلى إصدارات الصورة التي تم تغيير حجمها.

نشر حدث في قناة

يتم نشر أحداث Eventarc في قنوات. القنوات هي وسيلة لتجميع الأحداث ذات الصلة وإدارة أذونات الوصول. عند تثبيت إضافة أو نشر دالة تستهلك الأحداث المخصّصة، ينشئ Firebase تلقائيًا قناة تلقائية باسم firebase في منطقة us-central1. توفّر "حزمة SDK لمشرفي Firebase" حزمة فرعية 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 مع حزمة SDK للمشرف في Firebase:

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

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