مدیریت پیکربندی‌های پروژه با مانیفست «افزونه‌ها»

مانیفست افزونه‌ها فهرستی از نمونه‌های افزونه و پیکربندی‌های آن‌ها است. با مانیفست می‌توانید:

  • پیکربندی افزونه‌هایتان را با دیگران هم‌رسانی کنید
  • پیکربندی افزونه‌هایتان را بین پروژه‌های مختلف کپی کنید (مثلاً از پروژه مرحله‌ای به پروژه تولیدی)
  • همه افزونه‌هایتان را یک‌جا مستقر کنید
  • بااستفاده از 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}.firebasestorage.app
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 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 در پروژه‌ای مستقر کنید. وقتی با مانیفست افزونه‌ها استقرار می‌کنید، همه نمونه‌های افزونه در مانیفست را به‌طور هم‌زمان در یک پروژه نصب، به‌روزرسانی، و پیکربندی می‌کنید.

برای استقرار مانیفست افزونه‌ها:

  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 قرار دهید