نصب، پیکربندی، و ادغام «مجموعه شبیه‌ساز محلی»

«مجموعه شبیه‌ساز محلی Firebase» را می‌توان برای محیط‌های نمونه اولیه و آزمایشی مختلف نصب و پیکربندی کرد، از جلسات نمونه‌سازی یک‌باره گرفته تا گردش‌های کاری ادغام مداوم در مقیاس تولید.

نصب «مجموعه شبیه‌ساز محلی»

قبل‌از نصب «مجموعه شبیه‌ساز» به موارد زیر نیاز دارید:

  • Node.js نسخه ۱۶.۰ یا بالاتر.
  • Java JDK نسخه ۱۱ یا بالاتر.

برای نصب کردن «مجموعه شبیه‌ساز»:

  1. Firebase CLI را نصب کنید. اگر ازقبل «واسط خط فرمان Firebase» را نصب نکرده‌اید، اکنون آن را نصب کنید. برای استفاده از «مجموعه شبیه‌ساز»، به CLI نسخه ۸.۱۴.۰ یا بالاتر نیاز دارید. بااستفاده از فرمان زیر می‌توانید بررسی کنید کدام نسخه را نصب کرده‌اید:
    firebase --version
  2. اگر قبلاً این کار را نکرده‌اید، دایرکتوری کاری فعلی را به‌عنوان پروژه Firebase مقداردهی اولیه کنید و دستورالعمل‌های روی صفحه را برای مشخص کردن محصولات مورد استفاده دنبال کنید:
    firebase init
  3. «مجموعه شبیه‌ساز» را راه‌اندازی کنید. این فرمان یک جادوی پیکربندی را شروع می‌کند که به شما امکان می‌دهد شبیه‌سازهای موردنظر را انتخاب کنید، فایل‌های دودویی شبیه‌ساز مربوطه را بارگیری کنید، و اگر پیش‌فرض‌ها مناسب نیستند، درگاه‌های شبیه‌ساز را تنظیم کنید.
    firebase init emulators

پس‌از نصب شبیه‌ساز، هیچ بررسی به‌روزرسانی انجام نمی‌شود و هیچ بارگیری خودکار دیگری تا زمانی که نسخه Firebase CLI خود را به‌روز نکنید، رخ نخواهد داد.

پیکربندی «مجموعه شبیه‌ساز»

می‌توانید به‌طور اختیاری درگاه‌های شبکه شبیه‌سازها و مسیر تعاریف «قوانین امنیتی» را در فایل firebase.json پیکربندی کنید:

  • درگاه‌های شبیه‌ساز را با اجرای firebase init emulators یا با ویرایش دستی firebase.json تغییر دهید.
  • با ویرایش دستی firebase.json، مسیر تعاریف «قوانین امنیتی» را تغییر دهید.

اگر این تنظیمات را پیکربندی نکنید، شبیه‌سازها روی درگاه‌های پیش‌فرض خود گوش خواهند داد و شبیه‌سازهای Cloud Firestore، Realtime Database، و Cloud Storage for Firebase با امنیت داده‌های باز اجرا خواهند شد.

Command شرح
init emulators راه‌اندازی جادوی مقداردهی اولیه شبیه‌ساز. شبیه‌سازهایی را که باید نصب شوند شناسایی کنید و به‌طور اختیاری تنظیمات درگاه شبیه‌ساز را مشخص کنید. init emulators غیرمخرب است؛ پذیرفتن پیش‌فرض‌ها پیکربندی شبیه‌ساز فعلی را حفظ خواهد کرد.

پیکربندی درگاه

هر شبیه‌ساز به درگاه متفاوتی در دستگاه شما با مقدار پیش‌فرض ترجیحی متصل می‌شود.

شبیه‌ساز درگاه پیش‌فرض
Authentication 9099
App Hosting 5002
Emulator Suite UI 4000
Cloud Functions 5001
Eventarc 9299
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage for Firebase 9199
Firebase Hosting 5000
Pub/Sub 8085

پیکربندی شناسه پروژه

بسته به نحوه فراخوانی شبیه‌سازها، می‌توانید چندین نمونه از یک شبیه‌ساز را بااستفاده از شناسه‌های پروژه Firebase مختلف یا چندین نمونه شبیه‌ساز را برای یک شناسه پروژه مشخص اجرا کنید. در چنین مواردی، نمونه‌های شبیه‌ساز در محیطی جداگانه اجرا می‌شوند.

به‌طور کلی، روش خوب این است که یک شناسه پروژه برای همه فراخوانی‌های شبیه‌ساز تنظیم کنید تا Emulator Suite UI، شبیه‌سازهای مختلف محصول، و همه نمونه‌های درحال اجرای یک شبیه‌ساز خاص بتوانند در همه موارد به‌درستی ارتباط برقرار کنند.

Local Emulator Suite وقتی چند شناسه پروژه در محیط شناسایی می‌کند، هشدار صادر می‌کند، اما می‌توانید با تنظیم کلید singleProjectMode روی false در firebase.json، این رفتار را لغو کنید.

می‌توانید اظهارنامه(های) شناسه پروژه را برای عدم‌تطابق در موارد زیر بررسی کنید:

  • پروژه پیش‌فرض در خط فرمان. به‌طور پیش‌فرض، شناسه پروژه در زمان راه‌اندازی از پروژه انتخاب‌شده با firebase init یا firebase use گرفته می‌شود. برای مشاهده فهرست پروژه‌ها (و دیدن اینکه کدام‌یک انتخاب شده است) از firebase projects:list استفاده کنید.
  • آزمون‌های واحد قوانین. شناسه پروژه اغلب در تماس‌ها با روش‌های کتابخانه «آزمایش واحد قوانین» initializeTestEnvironment یا initializeTestApp مشخص می‌شود.
  • پرچم خط فرمان --project. با ارسال پرچم --project Firebase CLI، پروژه پیش‌فرض لغو می‌شود. باید مطمئن شوید مقدار پرچم با شناسه پروژه در آزمایش‌های واحد و مقداردهی اولیه برنامه مطابقت داشته باشد.

همچنین پیکربندی‌های شناسه پروژه مختص پلاتفرم را که هنگام پیکربندی پروژه‌های پلاتفرم‌های Apple، Android، و وب تنظیم کرده‌اید بررسی کنید.

پیکربندی «قوانین امنیتی»

شبیه‌سازها پیکربندی «قوانین امنیتی» را از کلیدهای پیکربندی database، firestore، و storage در firebase.json دریافت خواهند کرد.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

مشخص کردن گزینه‌های جاوا

شبیه‌ساز Realtime Database، شبیه‌ساز Cloud Firestore، و بخشی از شبیه‌ساز Cloud Storage for Firebase مبتنی بر Java هستند که می‌توان آن‌ها را با پرچم‌های JVM ازطریق متغیر محیطی JAVA_TOOL_OPTIONS سفارشی‌سازی کرد.

برای مثال، اگر با خطاهای مربوط به فضای پشته Java مواجه شدید، می‌توانید حداکثر اندازه پشته Java را به ۴ گیگابایت افزایش دهید:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

چند پرچم را می‌توان در نقل‌قول‌هایی که با فاصله از هم جدا شده‌اند مشخص کرد، مانند JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". پرچم‌ها فقط بر مؤلفه‌های مبتنی بر Java شبیه‌سازها تأثیر می‌گذارند و بر بخش‌های دیگر Firebase CLI، مثل Emulator Suite UI، تأثیری ندارند.

راه‌اندازی شبیه‌سازها

می‌توانید شبیه‌سازها را طوری راه‌اندازی کنید که تا زمانی که به‌صورت دستی متوقف شوند اجرا شوند، یا برای مدت‌زمان یک اسکریپت آزمایشی تعیین‌شده اجرا شوند و سپس به‌طور خودکار خاموش شوند.

Command شرح
emulators:start

شبیه‌سازها را برای محصولات Firebase پیکربندی‌شده در firebase.json راه‌اندازی کنید. فرایندهای شبیه‌ساز تا زمانی که صریحاً متوقف نشوند به اجرا ادامه خواهند داد. فراخوانی emulators:start شبیه‌سازها را در ~/.cache/firebase/emulators/ بارگیری می‌کند اگر ازقبل نصب نشده باشند.

پرچم شرح
--only اختیاری. محدود کردن شبیه‌سازهایی که شروع می‌شوند. فهرستی از نام‌های شبیه‌ساز را که با کاما از هم جدا شده‌اند ارائه دهید و یک یا چند مورد از موارد زیر را مشخص کنید: auth،‏ database،‏ firestore،‏ functions،‏ hosting، یا pubsub.
--inspect-functions DEBUG_PORT اختیاری. از شبیه‌ساز Cloud Functions برای فعال کردن اشکال‌زدایی نقطه توقف توابع در درگاه مشخص‌شده (یا درگاه پیش‌فرض 9229 درصورت حذف آرگومان) استفاده کنید. توجه داشته باشید که وقتی این پرچم ارائه می‌شود، شبیه‌ساز Cloud Functions به حالت اجرای سریالی خاصی تغییر می‌کند که در آن توابع در یک فرایند واحد، به‌ترتیب متوالی (FIFO) اجرا می‌شوند؛ این کار اشکال‌زدایی تابع را ساده می‌کند، اگرچه این رفتار با اجرای موازی و چندفرایندی توابع در ابر متفاوت است.
--export-on-exit= اختیاری. با شبیه‌ساز Authentication،‏ Cloud Firestore،‏ Realtime Database، یا Cloud Storage for Firebase استفاده کنید. به شبیه‌ساز(ها) دستور دهید که هنگام خاموش شدن، داده‌ها را به دایرکتوری صادر کنند، همان‌طور که برای فرمان emulators:export توضیح داده شده است. فهرست راهنمای برون‌برد را می‌توان با این پرچم مشخص کرد: firebase emulators:start --export-on-exit=./saved-data. اگر از --import استفاده شود، مسیر صادر کردن به‌طور پیش‌فرض همان است؛ برای مثال: firebase emulators:start --import=./data-path --export-on-exit. درنهایت، درصورت تمایل، مسیرهای دایرکتوری متفاوتی را به پرچم‌های --import و --export-on-exit ارسال کنید.
--import=IMPORT_DIRECTORY اختیاری. با شبیه‌ساز Authentication،‏ Cloud Firestore،‏ Realtime Database، یا Cloud Storage for Firebase استفاده کنید. داده‌های ذخیره‌شده بااستفاده از گزینه راه‌اندازی --export-on-exit یا فرمان emulators:export را به نمونه شبیه‌ساز Authentication، Cloud Firestore، Realtime Database، یا Cloud Storage for Firebase درحال اجرا وارد کنید. هر داده‌ای که درحال‌حاضر در حافظه شبیه‌ساز باشد رونویسی خواهد شد.
--log-verbosity=VERBOSITY اختیاری. میزان خروجی گزارش‌گیری از شبیه‌سازها را کاهش می‌دهد تا نویز در کنسول و فایل‌های گزارش کاهش یابد. مقادیر معتبر عبارت‌اند از DEBUG، INFO، QUIET، SILENT.
emulators:exec PATH/TO/SCRIPT

اسکریپت را در PATH/TO/SCRIPT پس‌از راه‌اندازی شبیه‌سازها برای محصولات Firebase پیکربندی‌شده در firebase.json اجرا کنید. وقتی که اجرای اسکریپت به‌پایان برسد، فرایندهای شبیه‌ساز به‌طور خودکار متوقف خواهد شد.

پرچم شرح
--only اختیاری. محدود کردن شبیه‌سازهایی که شروع می‌شوند. فهرستی از نام‌های شبیه‌ساز را که با کاما از هم جدا شده‌اند ارائه دهید و یک یا چند مورد از موارد زیر را مشخص کنید: firestore،‏ database،‏ functions،‏ hosting، یا pubsub.
--inspect-functions DEBUG_PORT اختیاری. برای فعال کردن اشکال‌زدایی نقطه توقف توابع در درگاه مشخص‌شده (یا درگاه پیش‌فرض 9229 درصورت حذف آرگومان)، از شبیه‌ساز Cloud Functions استفاده کنید. توجه داشته باشید که وقتی این پرچم ارائه می‌شود، شبیه‌ساز Cloud Functions به حالت اجرای سریالی خاصی تغییر می‌کند که در آن توابع در یک فرایند واحد، به‌ترتیب متوالی (FIFO) اجرا می‌شوند؛ این کار اشکال‌زدایی تابع را ساده می‌کند، اگرچه این رفتار با اجرای موازی و چندفرایندی توابع در ابر متفاوت است.
--export-on-exit= اختیاری. با شبیه‌ساز Authentication،‏ Cloud Firestore،‏ Realtime Database، یا Cloud Storage for Firebase استفاده کنید. به شبیه‌ساز(ها) دستور دهید که هنگام خاموش شدن، داده‌ها را به دایرکتوری صادر کنند، همان‌طور که برای فرمان emulators:export توضیح داده شده است. فهرست راهنمای برون‌برد را می‌توان با این پرچم مشخص کرد: firebase emulators:start --export-on-exit=./saved-data. اگر از --import استفاده شود، مسیر صادر کردن به‌طور پیش‌فرض همان است؛ برای مثال: firebase emulators:start --import=./data-path --export-on-exit. درنهایت، درصورت تمایل، مسیرهای دایرکتوری متفاوتی را به پرچم‌های --import و --export-on-exit ارسال کنید.
--import=IMPORT_DIRECTORY اختیاری. با شبیه‌ساز Authentication،‏ Cloud Firestore،‏ Realtime Database، یا Cloud Storage for Firebase استفاده کنید. داده‌های ذخیره‌شده بااستفاده از گزینه راه‌اندازی --export-on-exit یا فرمان emulators:export را به نمونه شبیه‌ساز Authentication، Cloud Firestore، Realtime Database، یا Cloud Storage for Firebase درحال اجرا وارد کنید. هر داده‌ای که درحال‌حاضر در حافظه شبیه‌ساز باشد رونویسی خواهد شد.
--ui اختیاری. رابط کاربری شبیه‌ساز را درطول اجرا اجرا کنید.
--log-verbosity=VERBOSITY اختیاری. میزان خروجی گزارش‌گیری از شبیه‌سازها را کاهش می‌دهد تا نویز در کنسول و فایل‌های گزارش کاهش یابد. مقادیر معتبر عبارت‌اند از DEBUG، INFO، QUIET، SILENT.

روش firebase emulators:exec معمولاً برای گردش‌های کاری ادغام مداوم مناسب‌تر است.

صادر و وارد کردن داده‌های شبیه‌ساز

می‌توانید داده‌ها را از شبیه‌سازهای Authentication، Cloud Firestore، Realtime Database، و Cloud Storage for Firebase صادر کنید تا به‌عنوان مجموعه داده‌های پایه مشترک و قابل‌هم‌رسانی استفاده شود. این مجموعه‌های داده را می‌توان بااستفاده از پرچم --import وارد کرد، همان‌طور که در بالا توضیح داده شد.

emulators:export export_directory

شبیه‌ساز Authentication،‏ Cloud Firestore،‏ Realtime Database، یا Cloud Storage for Firebase. صادر کردن داده‌ها از نمونه شبیه‌ساز Cloud Firestore، Realtime Database، یا Cloud Storage for Firebase درحال اجرا. اگر export_directory مشخص‌شده ازقبل وجود نداشته باشد، ایجاد خواهد شد. اگر دایرکتوری مشخص‌شده وجود داشته باشد، از شما خواسته می‌شود تأیید کنید که داده‌های برون‌برد قبلی باید رونویسی شود. می‌توانید بااستفاده از پرچم --force از این پیام‌واره رد شوید. فهرست راهنمای صادرشده حاوی فایل مانیفست داده، firebase-export-metadata.json، است.

می‌توانید به شبیه‌سازها دستور دهید که هنگام خاموش شدن، داده‌ها را به‌طور خودکار بااستفاده از پرچم‌های --export-on-exit که در بالا شرح داده شده است صادر کنند.

ادغام با سیستم CI شما

درحال اجرای تصاویر «مجموعه شبیه‌ساز» محفظه‌بندی‌شده

نصب و پیکربندی «مجموعه شبیه‌ساز» با محفظه‌ها در یک راه‌اندازی CI معمولی ساده است.

چند مشکل وجود دارد که باید به آن‌ها توجه کنید:

  • فایل‌های JAR در ~/.cache/firebase/emulators/ نصب و ذخیره موقت می‌شوند.

    • شاید بخواهید این مسیر را به پیکربندی حافظه نهان CI اضافه کنید تا از بارگیری‌های مکرر جلوگیری شود.
  • اگر فایل firebase.json در مخزن خود ندارید، باید یک آرگومان خط فرمان به دستور emulators:start یا emulators:exec اضافه کنید تا مشخص شود کدام شبیه‌سازها باید راه‌اندازی شوند. برای مثال،
    --only functions,firestore.

تولید کردن یک کد اصالت‌سنجی (فقط شبیه‌ساز میزبانی)

اگر گردش‌های کاری ادغام مداوم شما به Firebase Hosting متکی است، باید بااستفاده از یک توکن به سیستم وارد شوید تا بتوانید firebase emulators:exec را اجرا کنید. شبیه‌سازهای دیگر به ورود به سیستم نیاز ندارند.

برای تولید کردن یک کد، firebase login:ci را در محیط محلی خود اجرا کنید؛ این کار نباید از سیستم CI انجام شود. دستورالعمل‌ها را برای اصالت‌سنجی کردن دنبال کنید. این مرحله را فقط باید یک‌بار برای هر پروژه انجام دهید، زیرا این کد در سراسر ساخت‌ها معتبر خواهد بود. با این کد باید مانند گذرواژه رفتار شود؛ مطمئن شوید که مخفی نگه داشته می‌شود.

اگر محیط CI به شما اجازه می‌دهد متغیرهای محیطی را که می‌توانند در اسکریپت‌های ساخت استفاده شوند مشخص کنید، کافی است یک متغیر محیطی به نام FIREBASE_TOKEN ایجاد کنید که مقدار آن رشته کد دسترسی باشد. واسط خط فرمان Firebase به‌طور خودکار متغیر محیطی FIREBASE_TOKEN را انتخاب می‌کند و شبیه‌سازها به‌درستی شروع می‌شوند.

به‌عنوان آخرین راهکار، می‌توانید به‌سادگی توکن را در اسکریپت ساخت خود قرار دهید، اما مطمئن شوید که اشخاص غیرقابل‌اعتماد به آن دسترسی ندارند. برای این رویکرد کدگذاری‌شده، می‌توانید --token "YOUR_TOKEN_STRING_HERE" را به فرمان firebase emulators:exec اضافه کنید.

استفاده از Emulator Hub REST API

فهرست کردن شبیه‌سازهای درحال اجرا

برای فهرست کردن شبیه‌سازهای درحال اجرای فعلی، درخواست GET را به نقطه پایانی /emulators «مرکز شبیه‌ساز» ارسال کنید.

curl localhost:4400/emulators

نتیجه یک شیء JSON خواهد بود که همه شبیه‌سازهای درحال اجرا و پیکربندی میزبان/درگاه آن‌ها را فهرست می‌کند، برای مثال:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

فعال/غیرفعال کردن راه‌اندازهای عملکرد پس‌زمینه

در برخی شرایط، باید راه‌اندازهای افزونه و عملکرد محلی را موقتاً غیرفعال کنید. برای مثال، ممکن است بخواهید همه داده‌های موجود در شبیه‌ساز Cloud Firestore را بدون راه‌اندازی هیچ‌کدام از تابع‌های onDelete که در شبیه‌سازهای Cloud Functions یا Extensions درحال اجرا هستند حذف کنید.

برای غیرفعال کردن موقت راه‌اندازهای تابع محلی، درخواست PUT را به نقطه پایانی /functions/disableBackgroundTriggers در «مرکز شبیه‌ساز» ارسال کنید.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

نتیجه یک شیء JSON خواهد بود که جزئیات وضعیت فعلی را نشان می‌دهد.

{
  "enabled": false
}

برای فعال کردن راه‌اندازهای تابع محلی پس‌از غیرفعال شدن، درخواست PUT را به نقطه پایانی /functions/enableBackgroundTriggers در Emulator Hub ارسال کنید.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

نتیجه یک شیء JSON خواهد بود که جزئیات وضعیت فعلی را نشان می‌دهد.

{
  "enabled": true
}

ادغام‌های کیت توسعه نرم‌افزار شبیه‌ساز

جدول‌های این بخش نشان می‌دهند که کدام شبیه‌سازها توسط کارخواه و کیت‌های توسعه نرم‌افزار سرپرست پشتیبانی می‌شوند. آینده یعنی پشتیبانی از شبیه‌ساز برنامه‌ریزی شده است اما هنوز دردسترس نیست.

دردسترس بودن کیت توسعه نرم‌افزار مشتری

Android پلاتفرم‌های Apple وب Firebase UI
Android
Firebase UI
iOS
Firebase UI
وب
Realtime Database ‫۱۹.۴.۰ 7.2.0 8.0.0 6.4.0 آینده نامربوط
Cloud Firestore ‫۲۱.۶.۰ 7.2.0 8.0.0 6.4.0 آینده نامربوط
Authentication ‫۲۰.۰.۰ 7.0.0 8.0.0 7.0.0 آینده ‫۴.۷.۲
Cloud Storage for Firebase ‫۲۰.۰.۰ 8.0.0 8.4.0 7.0.0 11.0.0 نامربوط
Cloud Functions ‫۱۹.۱.۰ 7.2.0 8.0.0 نامربوط نامربوط نامربوط
Hosting نامربوط نامربوط نامربوط نامربوط نامربوط نامربوط
Extensions نامربوط نامربوط نامربوط نامربوط نامربوط نامربوط

دردسترس بودن Admin SDK

Node جاوا Python Go
Realtime Database ‫۸.۶.۰ 6.10.0 ‫۲.۱۸.۰ آینده
Cloud Firestore 8.0.0 6.10.0 3.0.0 ۱.۰.۰
Authentication 9.3.0 7.2.0 5.0.0 4.2.0
Cloud Storage for Firebase 9.8.0 آینده آینده آینده
Cloud Functions نامربوط نامربوط نامربوط نامربوط
Hosting نامربوط نامربوط نامربوط نامربوط
Extensions نامربوط نامربوط نامربوط نامربوط