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

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

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

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

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

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

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

إدارة بيان الإضافات باستخدام واجهة سطر الأوامر في 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. عليك إعداد واجهة سطر الأوامر في Firebase، إذا لم يسبق لك إعدادها.
2. من موجّه الأوامر، انتقِل إلى دليل المشروع. (يحتوي دليل المشروع على الملف firebase.json).
3. تنفيذ الأمر ext:export:

   firebase ext:export

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

اختبار إعدادات الإضافات باستخدام "مجموعة أدوات المحاكي المحلي في Firebase"

بعد إدراج بعض مثيلات الإضافات في بيان الإضافات، يمكنك اختبارها باستخدام "حزمة أدوات المحاكاة المحلية".

1. ثبِّت "مجموعة أدوات المحاكاة المحلية" واضبطها.

2. بدء تشغيل "مجموعة أدوات المحاكاة المحلية":

   • لتشغيل Emulator Suite بشكل تفاعلي، شغِّل: firebase emulators:start
   • لتشغيل Emulator Suite وتنفيذ نص برمجي تجريبي، شغِّل: firebase emulators:exec my-test.sh

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

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

بعد إدراج بعض مثيلات الإضافة إلى بيان الإضافة، يمكنك نشرها في مشروع باستخدام واجهة سطر الأوامر في 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

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

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