إضافة عناصر الجذب للمستخدمين إلى إضافة

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

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

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

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

فعاليات 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: قائمة مفصولة بفواصل لأنواع الأحداث التي نفّذها المستخدم اختيار النشر عند إعداد قناة بهذه القيمة، تعمل حزمة "SDK للمشرف" على فلترة الأحداث التي لم يحدِّدها المستخدم تلقائيًا.
   • EVENTARC_CLOUD_EVENT_SOURCE: معرّف مصدر الحدث على السحابة الإلكترونية تشير رسالة الأشكال البيانية تمرِّر حزمة تطوير البرامج (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();
    });

الاطّلاع على عوامل تشغيل الأحداث المخصّصة لمزيد من المعلومات المعلومات.

مثال

إضافة تغيير حجم الصور الرسمية توفّر عنصر جذب غير متزامن من خلال النشر على 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/v1');
   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 توفّر عنصر جذب متزامن لطلب دالة التحويل التي يوفرها المستخدم قبل الكتابة إلى ألغوليا.