إضافة خطافات المستخدم إلى ملحق

يمكنك تزويد المستخدمين الذين قاموا بتثبيت ملحقك بالقدرة على إدراج المنطق المخصص الخاص بهم في تنفيذ ملحقك. توجد هناك طريقتين لانجاز هذا:

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

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

يمكن للملحق استخدام إحدى الطريقتين أو كلتيهما.

أحداث إيفنتارك

لنشر الأحداث من ملحق:

1. قم بتعريف أنواع الأحداث التي ستنشرها في ملف extension.yaml :

   events:
     - type: publisher-id.extension-name.version.event-name
       description: event-description
     - type: publisher-id.extension-name.version.another-event-name
       description: another-event-description
   

   يتكون معرف type من عدة حقول محددة بنقاط. حقول معرف الناشر واسم الملحق واسم الحدث مطلوبة. يوصى باستخدام حقل الإصدار. اختر اسم حدث فريدًا ووصفيًا لكل نوع حدث تنشره.

   على سبيل المثال، يعلن الامتداد storage-resize-images عن نوع حدث واحد:

   events:
     - type: firebase.extensions.storage-resize-images.v1.complete
       description: |
         Occurs when image resizing completes. The event will contain further
         details about specific formats and sizes.
   

   سيتمكن المستخدمون من اختيار الأحداث التي يريدون الاشتراك فيها عند تثبيت الامتداد.

2. في وظائف الامتداد الخاصة بك، قم باستيراد Eventarc API من Admin SDK وقم بتهيئة قناة حدث باستخدام إعدادات التثبيت الخاصة بالمستخدم. يتم عرض هذه الإعدادات باستخدام متغيرات البيئة التالية:

   • EVENTARC_CHANNEL : الاسم المؤهل بالكامل لقناة Eventarc التي اختار المستخدم نشر الأحداث عليها.
   • EXT_SELECTED_EVENTS : قائمة مفصولة بفواصل لأنواع الأحداث التي اختار المستخدم نشرها. عند تهيئة قناة بهذه القيمة، تقوم Admin SDK تلقائيًا بتصفية الأحداث التي لم يحددها المستخدم.
   • EVENTARC_CLOUD_EVENT_SOURCE : معرف مصدر Cloud Event. يقوم Admin SDK تلقائيًا بتمرير هذه القيمة في الحقل source للأحداث المنشورة. لا تحتاج عادةً إلى استخدام هذا المتغير بشكل صريح.

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

   import * as admin from "firebase-admin";
   import {getEventarc} from 'firebase-admin/eventarc';
   
   admin.initializeApp();
   
   // Set eventChannel to a newly-initialized channel, or `undefined` if events
   // aren't enabled.
   const eventChannel =
     process.env.EVENTARC_CHANNEL &&
     getEventarc().channel(process.env.EVENTARC_CHANNEL, {
       allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
     });
   

3. انشر الأحداث على القناة في النقاط الموجودة في ملحقك والتي تريد عرضها للمستخدمين. على سبيل المثال:

   // If events are enabled, publish a `complete` event to the configured
   // channel.
   eventChannel && eventChannel.publish({
       type: 'firebase.extensions.storage-resize-images.v1.complete',
       subject: filename,  // the name of the original file
       data: {
         // ...
       }
   });
   

4. قم بتوثيق الأحداث التي تنشرها، إما في ملف PREINSTALL أو POSTINSTALL.

   قم بتوثيق ما يلي لكل حدث:

   • الغرض المقصود منه
   • النقطة في منطق الامتداد الخاص بك الذي يتم تشغيله
   • بيانات الإخراج التي يتضمنها
   • شروط تنفيذه

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

عند نشر أحداث من ملحق، يمكن للمستخدمين نشر معالجات الأحداث للاستجابة باستخدام المنطق المخصص.

على سبيل المثال، يقوم المثال التالي بحذف الصورة الأصلية بعد أن تم تغيير حجمها. لاحظ أن معالج المثال هذا يستخدم خاصية subject للحدث، وهو في هذه الحالة اسم الملف الأصلي للصورة.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

راجع مشغلات الأحداث المخصصة لمزيد من المعلومات.

مثال

يوفر ملحق Resize Images الرسمي ربطًا غير متزامن عن طريق النشر على Eventarc بعد تغيير حجم الصورة.

خطافات متزامنة

عندما تريد تزويد المستخدمين بخطاف يجب إكماله بنجاح حتى تعمل إحدى وظائف الامتداد، استخدم الخطافات المتزامنة .

يستدعي الخطاف المتزامن وظيفة السحابة القابلة للاستدعاء HTTPS المعرفة من قبل المستخدم وينتظر الاكتمال (ربما مع قيمة تم إرجاعها) قبل المتابعة. يؤدي خطأ في الوظيفة المقدمة من قبل المستخدم إلى خطأ في وظيفة الامتداد.

لكشف الخطاف المتزامن:

1. أضف معلمة إلى ملحقك الذي يسمح للمستخدمين بتكوين الامتداد باستخدام عنوان URL لوظيفة السحابة المخصصة الخاصة بهم. على سبيل المثال:

   - param: PREPROCESSING_FUNCTION
     label: Pre-processing function URL
     description: >
       An HTTPS callable function that will be called to transform the input data
       before it is processed by this function.
     type: string
     example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
     required: false
   

2. عند النقطة في ملحقك حيث تريد كشف الخطاف، اتصل بالوظيفة باستخدام عنوان URL الخاص بها. على سبيل المثال:

   const functions = require('firebase-functions');
   const fetch = require('node-fetch');
   
   const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;
   
   exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
       .onWrite((change, context) => {
         // PREPROCESSING_FUNCTION hook begins here.
         // If a preprocessing function is defined, call it before continuing.
         if (preprocessFunctionURL) {
           try {
             await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
           } catch (e) {
             // Preprocessing failure causes the function to fail.
             functions.logger.error("Preprocessor error:", e);
             return;
           }
         }
         // End of PREPROCESSING_FUNCTION hook.
   
         // Main function logic follows.
         // ...
       });
   

3. قم بتوثيق أي خطافات تجعلها متاحة في ملف PREINSTALL أو POSTINSTALL.

   لكل خطاف، قم بتوثيق ما يلي:

   • الغرض المقصود منه
   • النقطة في منطق الامتداد الخاص بك الذي يتم تشغيله
   • مدخلاتها ومخرجاتها المتوقعة
   • الشروط (أو الخيارات) لتنفيذه

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

مثال

يوفر ملحق Algolia Search خطافًا متزامنًا لاستدعاء وظيفة التحويل التي يوفرها المستخدم قبل الكتابة إلى Algolia.