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

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

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

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

  • يمثّل 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

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

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

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

نوضّح أدناه الطريقتَين الأوليَين.

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

يمكنك تنفيذ معظم أوامر ext: في واجهة سطر الأوامر الخاصة بـ Firebase باستخدام الخيار --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. إعداد واجهة سطر الأوامر (CLI) في Firebase، إذا لم يسبق لك إجراء ذلك
  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
    • لتشغيل Emulator Suite وتنفيذ نص برمجي للاختبار، شغِّل ما يلي: firebase emulators:exec my-test.sh

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

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

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

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

  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.

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

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