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

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

• مشاركة إعدادات إضافاتك مع مستخدمين آخرين
• نسخ إعدادات إضافاتك بين مشاريع مختلفة (مثل نقلها من مشروعك التجريبي إلى مشروعك الذي تم إطلاقه)
• نشر جميع إضافاتك في آنٍ واحد
• اختبار طريقة عمل إضافاتك مع تطبيقك باستخدام 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

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

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

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

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

إدارة بيان إضافاتك باستخدام Firebase CLI

يمكنك تنفيذ معظم أوامر 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