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

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

  • مشاركة إعدادات الإضافات مع الآخرين
  • نسخ إعدادات الإضافات بين المشاريع المختلفة (مثل من مشروعك التجريبي إلى مشروعك الإنتاجي)
  • نشر جميع الإضافات في آنٍ واحد
  • اختبِر طريقة عمل الإضافات مع تطبيقك باستخدام 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}.firebasestorage.app
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

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

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

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

في ما يلي شرح للطريقتَين الأوليَين.

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

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

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

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

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

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

# 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. من موجّه واجهة الأوامر، انتقِل إلى دليل المشروع. (يحتوي دليل مشروعك على الملف 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 CLI. عند النشر باستخدام ملف بيان الإضافات، يمكنك تثبيت جميع نُسخ الإضافات في ملف البيان وتحديثها وضبطها في مشروع واحد في آنٍ واحد.

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

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

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

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

يمكن استخدام إعدادات الإضافات المحفوظة للنشر في عدة مشاريع مختلفة: على سبيل المثال، مشروع مرحلي ومشروع إنتاج. عند إجراء ذلك، قد تحتاج بعض قيم المَعلمات إلى أن تكون مختلفة لكل مشروع. تتيح ملفات .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