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

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

• أحداث Eventarc: لمنح المستخدمين طريقة للتفاعل بشكل غير متزامن مع الأحداث، يمكنك النشر على 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 من حزمة 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');
   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.