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

بيان الامتدادات عبارة عن قائمة بمثيلات الامتداد وتكويناتها. مع البيان، يمكنك:

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

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

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

نشر تكوين ملحقات لمشروع

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

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

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