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

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

• أحداث 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 Search خطافًا متزامنًا للاتّصال بوظيفة تحويل يقدّمها المستخدم قبل الكتابة إلى Algolia.