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

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

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

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

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

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

1. من موجّه shell، انتقِل إلى الدليل الذي يحتوي على ملف إعدادات الإضافات المحفوظ. (هذا هو الدليل الذي يحتوي على firebase.json. إذا كنت قد نفّذت للتو ext:export، يعني ذلك أنّك في الкатаloog الصحيح.)
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