بيان الإضافات هو قائمة بمثيلات الإضافات وإعداداتها. باستخدام البيان، يمكنك إجراء ما يلي:
- مشاركة إعداد الإضافات مع الآخرين
- انسخ إعدادات الإضافات بين مشاريع مختلفة (على سبيل المثال من مشروعك المرحلي إلى مشروع الإنتاج)
- نشر جميع الإضافات دفعة واحدة
- اختبار آلية عمل الإضافات مع تطبيقك باستخدام "مجموعة أدوات المحاكاة المحلية من 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
تصدير إعدادات إضافات مشروع
لحفظ الإعداد الحالي للإضافات لمشروع في البيان، اتّبِع الخطوات التالية:
- عليك إعداد واجهة سطر الأوامر في Firebase، إذا لم يسبق لك إعدادها.
- من موجّه الأوامر، انتقِل إلى دليل المشروع. (يحتوي دليل المشروع
على الملف
firebase.json
). - تنفيذ الأمر
ext:export
:firebase ext:export
سيضيف الأمر ext:export
القسم extensions
إلى ملف firebase.json
. بالإضافة إلى ذلك، ينشئ الأمر ext:export
دليل extensions
يحتوي على ملف .env
لكل مثيل إضافة ثبَّته. تحتوي هذه
الملفات على معلمات التهيئة لكل مثيل.
اختبار إعدادات الإضافات باستخدام "مجموعة أدوات المحاكي المحلي في Firebase"
بعد إدراج بعض مثيلات الإضافات في بيان الإضافات، يمكنك اختبارها باستخدام "حزمة أدوات المحاكاة المحلية".
بدء تشغيل "مجموعة أدوات المحاكاة المحلية":
- لتشغيل Emulator Suite بشكل تفاعلي، شغِّل:
firebase emulators:start
- لتشغيل Emulator Suite وتنفيذ نص برمجي تجريبي، شغِّل:
firebase emulators:exec my-test.sh
- لتشغيل Emulator Suite بشكل تفاعلي، شغِّل:
الآن، إذا كانت مثيلات الإضافات مدرَجة في البيان، ستنزّل
حزمة أدوات المحاكاة المحلية رمز المصدر لهذه الإضافات إلى
~/.cache/firebase/extensions
. وبعد تنزيلها، ستبدأ "مجموعة أدوات المحاكي المحلي"
وستتمكّن من تشغيل أيّ من
الوظائف التي تظهر في الخلفية للإضافات وربط تطبيقك بحزمة "المحاكي"
لاختبار تكاملها مع تطبيقك.
نشر إعداد إضافات في مشروع
بعد إدراج بعض مثيلات الإضافة إلى بيان الإضافة، يمكنك نشرها في مشروع باستخدام واجهة سطر الأوامر في Firebase. عند النشر باستخدام بيان الإضافات، يمكنك تثبيت جميع مثيلات الإضافات في البيان وتحديثها وإعدادها في مشروع مرة واحدة.
لنشر بيان الإضافات:
- من موجّه الأوامر، انتقِل إلى الدليل الذي يحتوي على إعدادات الإضافات المحفوظة. (هذا هو الدليل الذي يحتوي على
firebase.json
. إذا شغّلت للتوext:export
، فأنت في الدليل الصحيح.) - شغِّل الأمر
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