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

باستخدام 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 . أولاً، عليك استيراد هذا المعالِج من حزمة تطوير البرامج (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