إدارة إعدادات المشروع باستخدام بيان "الإضافات"

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

• مشاركة إعدادات الإضافات مع الآخرين
• نسخ إعدادات الإضافات بين مشاريع مختلفة (مثلاً من مشروعك التجريبي إلى مشروعك العلني)
• نشر جميع الإضافات دفعة واحدة
• اختبار أداء إضافاتك مع تطبيقك باستخدام Firebase Local Emulator Suite
• ضبط إعدادات الإضافات في أداة التحكّم في المصدر
• تضمين الإضافات في مسار عملية التطوير/النشر المتكاملَين

يتألّف بيان الإضافات من جزأين:

• القسم extensions من firebase.json، وهو خريطة لرقم تعريف المثيل لمرجع إصدار الإضافة. على سبيل المثال:

  {
   "extensions": {
     "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
     "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
   }
  }
  

• ملفات .env التي تحتوي على إعدادات كل مثيل من مثيلات الإضافة ، في الدليل الفرعي extensions/ ضمن دليل مشروعك على Firebase على سبيل المثال، قد يتضمّن مثيل storage-resize-imagesملف .env على النحو التالي:

  IMAGE_TYPE=jpeg
  LOCATION=us-central1
  IMG_BUCKET=${param:PROJECT_ID}.appspot.com
  IMG_SIZES=100x100
  DELETE_ORIGINAL_FILE=false

إنشاء ملف بيان إضافات

هناك ثلاث طرق لإنشاء بيان إضافات:

• إدارة بيان الإضافات باستخدام واجهة برمجة التطبيقات Firebase CLI
• تصدير إعدادات إضافات المشروع
• تعديل ملفات البيان يدويًا

يتم شرح أول طريقتين أدناه.

إدارة بيان الإضافات باستخدام واجهة برمجة التطبيقات Firebase CLI

يمكنك تنفيذ معظم أوامر ext: في Firebase CLI باستخدام الخيار --local لتعديل بيان الإضافات بدون تغيير الإعدادات الحالية للمشروع.

على سبيل المثال:

firebase ext:install --local firebase/firestore-bigquery-export

سيطلب منك تنفيذ الأمر أعلاه ضبط أحدث إصدار من إضافة firebase/firestore-bigquery-export وحفظ الإعدادات في البيان، ولكن لن يتم نشر الإعدادات في مشروعك.

في ما يلي بعض الأمثلة الإضافية على الأوامر التي تعدّل بيان ملحق Chrome:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

تصدير إعدادات إضافات المشروع

لحفظ إعدادات الإضافات الحالية للمشروع في البيان، اتّبِع الخطوات التالية:

1. إعداد واجهة برمجة التطبيقات Firebase CLI إذا لم يسبق لك إجراء ذلك
2. من موجه shell، انتقِل إلى دليل المشروع. (يحتوي ملف directory الخاص بمشروعك على الملف firebase.json).
3. نفِّذ الأمر ext:export:

   firebase ext:export

سيؤدي الأمر ext:export إلى إضافة قسم extensions إلى الملف firebase.json. بالإضافة إلى ذلك، ينشئ الأمر ext:export دليل extensions يحتوي على ملف .env لكل مثيل إضافة ثبَّته. تحتوي هذه الملفات على معلمات التهيئة لكل مثيل.

اختبار إعدادات الإضافات باستخدام Firebase Local Emulator Suite

بعد إدراج بعض مثيلات الإضافات في بيان الإضافات، يمكنك اختبارها باستخدام Local Emulator Suite.

1. ثبِّت Local Emulator Suite واضبطه.

2. بدء Local Emulator Suite:

   • لتشغيل "مجموعة أدوات المحاكاة" بشكل تفاعلي، شغِّل: firebase emulators:start
   • لتشغيل حزمة المحاكيات وتنفيذ نص برمجي اختباري، شغِّل: firebase emulators:exec my-test.sh

الآن، إذا كانت لديك نُسخ من الإضافات مُدرَجة في البيان، سينزيل الرمز المصدر لهذه الإضافات من Local Emulator Suite إلى ~/.cache/firebase/extensions. بعد تنزيلها، سيبدأ Local Emulator Suite وستتمكّن من بدء أي من وظائف الإضافات التي يتم تشغيلها في الخلفية وربط تطبيقك بمجموعة المحاكي لاختبار دمجها مع تطبيقك.

نشر إعداد إضافات في مشروع

بعد إدراج بعض مثيلات الإضافة في بيان الإضافة، يمكنك نشرها في مشروع باستخدام واجهة سطر الأوامر في Firebase. عند النشر باستخدام بيان الإضافات، يتم تثبيت جميع مثيلات الإضافة في البيان وتحديثها وضبطها في مشروع واحد في آنٍ واحد.

لنشر بيان إضافات:

1. من موجّه الأوامر، انتقِل إلى الدليل الذي يحتوي على إعدادات الإضافات المحفوظة. (هذا هو الدليل الذي يحتوي على firebase.json. إذا شغّلت للتو ext:export، فأنت في الدليل الصحيح.)
2. نفِّذ الأمر deploy. وإذا كنت تريد نشر الإضافات في مشروع غير المشروع الحالي، حدِّد أيضًا --project=:

   firebase deploy --only extensions –-project=YOUR_PROJECT_ID

سيتحقّق الأمر deploy من صحة إعدادات كلّ مثيل، وسيسألك عمّا إذا كنت تريد حذف أيّ نُسخ من الإضافة من مشروع الوجهة غير المُدرَجة في firebase.json، ثمّ سينشر كلّ نُسخ الإضافة.

إعدادات الإضافات الخاصة بالمشروع

يمكن استخدام إعدادات الإضافات المحفوظة للنشر في عدة projects مختلفة: على سبيل المثال، مشروع تنظيم ومشروع اختبار علني. عند إجراء ذلك، قد تحتاج بعض قيم المَعلمات إلى أن تكون مختلفة لكل مشروع. تتيح ملفات .env الخاصة بالمشروع إجراء ذلك:

• ضع قيم المَعلمات التي تختلف بين المشاريع في extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
• ضَع قيم المَعلمات المشترَكة في extensions/EXTENSION_INSTANCE_ID.env.

في بعض الأحيان، قد تحتاج إلى استخدام قيمة مَعلمة مختلفة عند محاكاة الإضافات: على سبيل المثال، قد تحتاج إلى تقديم مفتاح اختبار لواجهة برمجة التطبيقات بدلاً من مفتاح الإصدار العلني. ضَع المَعلمات التالية في ملف .local:

• ضع المعلَمات غير السرية التي تريد استخدامها أثناء المحاكاة في extensions/EXTENSION_INSTANCE_ID.env.local
• ضع قيم المَعلمات السرية في extensions/EXTENSION_INSTANCE_ID.secret.local