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

بيان الامتدادات هو قائمة بطبعات الامتدادات وتكويناتها. باستخدام البيان ، يمكنك:

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

    • لتشغيل 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