התקנה, הגדרה ושילוב של חבילת אמולטור מקומי

אפשר להתקין את Firebase Local Emulator Suite ולהגדיר אותו לסביבות שונות של אב טיפוס ובדיקות, החל מפעילויות חד-פעמיות של יצירת אב טיפוס ועד לתהליכי עבודה של שילוב רציף (CI) בקנה מידה תעשייתי.

התקנת Local Emulator Suite

לפני שמתקינים את Emulator Suite, צריך:

• Node.js מגרסה 16.0 ואילך.
• JDK של Java מגרסה 11 ואילך.

כדי להתקין את Emulator Suite:

1. מתקינים את Firebase CLI. אם עדיין לא התקנתם את Firebase CLI, מתקינים אותו עכשיו. כדי להשתמש ב-Emulator Suite, צריך CLI מגרסה 8.14.0 ואילך. אפשר לבדוק באיזו גרסה אתם משתמשים באמצעות הפקודה הבאה:

   firebase --version

2. אם עדיין לא עשיתם זאת, צריך לאתחל את ספריית העבודה הנוכחית כפרויקט ב-Firebase, ופועלים לפי ההנחיות במסך כדי לציין את המוצרים שבהם רוצים להשתמש:

   firebase init

3. מגדירים את Emulator Suite. הפקודה הזו מפעילה אשף תצורה שמאפשר לבחור את הסימולטורים הרצויים, להוריד את הקבצים הבינאריים המתאימים של הסימולטורים ולהגדיר את יציאות הסימולטורים אם הגדרות ברירת המחדל לא מתאימות.

   firebase init emulators

אחרי שמתקינים אמולטור, לא מתבצעות בדיקות עדכונים ולא מתבצעות הורדות אוטומטיות נוספות עד שמעדכנים את הגרסה של Firebase CLI.

הגדרת Emulator Suite

אפשר גם להגדיר את נתיבי הרשת של המהדמנים ואת הנתיב להגדרות של כללי האבטחה בקובץ firebase.json:

• כדי לשנות את יציאות הסימולטור, מריצים את הפקודה firebase init emulators או עורכים את הקובץ firebase.json באופן ידני.
• כדי לשנות את הנתיב להגדרות של כללי האבטחה, עורכים את firebase.json באופן ידני.

אם לא תגדירו את ההגדרות האלה, הסימולטורים יקשיבו ביציאות ברירת המחדל שלהם, והסימולטורים של Cloud Firestore, ‏ Realtime Database ו-Cloud Storage for Firebase יפעלו עם אבטחת נתונים פתוחה.

פקודה	תיאור
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 בשורת הפקודה. העברת הדגל Firebase CLI --project מבטלת את פרויקט ברירת המחדל. צריך לוודא שהערך של הדגל תואם למזהה הפרויקט בבדיקות היחידה ובהפעלת האפליקציה.

כדאי גם לבדוק את ההגדרות של מזהי הפרויקטים שמוגדרות ספציפית לפלטפורמה, שהגדרתם בזמן ההגדרה של פרויקטים ב-פלטפורמות של 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"
    }
  }
}

ציון אפשרויות של Java

הסימולטור של Realtime Database, הסימולטור של Cloud Firestore וחלק מהסימולטור של Cloud Storage for Firebase מבוססים על Java, שאפשר להתאים אישית באמצעות דגלים של JVM דרך משתנה הסביבה JAVA_TOOL_OPTIONS.

לדוגמה, אם נתקלתם בשגיאות שקשורות למרחב האשפה של Java, תוכלו להגדיל את גודל האשפה המקסימלי של Java ל-4GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

אפשר לציין כמה דגלים במירכאות, מופרדים ברווחים, כמו JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". הדגלים משפיעים רק על הרכיבים של המהדמנים שמבוססים על Java, ואין להם השפעה על חלקים אחרים של CLI של Firebase, כמו Emulator Suite UI.

הפעלת אמולטורים

אפשר להפעיל את הסימולטורים כך שיפעלו עד לסיום ידני, או שיפעלו למשך סקריפט הבדיקה הייעודי ולאחר מכן יושבתו באופן אוטומטי.

פקודה	תיאור
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. כל הנתונים שנמצאים כרגע בזיכרון של המהדר יימחקו.
emulators:exec scriptpath	מריצים את הסקריפט ב-scriptpath אחרי שמפעילים את הסימולטורים של מוצרי Firebase שהוגדרו ב-firebase.json. תהליכי הסימולטור יפסיקו באופן אוטומטי כשהסקריפט יסתיים. דגל תיאור --only אופציונלי. הגבלת האמולטורים שיופעלו. יש לספק רשימה של שמות של מכונות וירטואליות, מופרדים בפסיקים, ולציין לפחות אחד מהשמות הבאים: firestore,‏ database,‏ 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. כל הנתונים שנמצאים כרגע בזיכרון של המהדר יוחלפו. --ui אופציונלי. הרצת ממשק המשתמש של האמולטור במהלך ההפעלה.

השיטה firebase emulators:exec מתאימה בדרך כלל לתהליכי עבודה של שילוב רצוף (CI).

ייצוא וייבוא של נתוני אמולטור

אפשר לייצא נתונים מהמעבדים הווירטואליים 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

הפעלת קובצי אימג' של Emulator Suite בקונטיינרים

קל להתקין ולהגדיר את Emulator Suite עם קונטיינרים בהגדרת CI רגילה.

יש כמה בעיות שכדאי לשים לב אליהן:

• קובצי JAR מותקנים ונשמרים במטמון בכתובת ~/.cache/firebase/emulators/.

  • מומלץ להוסיף את הנתיב הזה להגדרת המטמון של CI כדי למנוע הורדות חוזרות.

• אם אין לכם קובץ firebase.json במאגר, תצטרכו להוסיף ארגומנט לשורת הפקודה לפקודה emulators:start או emulators:exec כדי לציין אילו מכונות וירטואליות צריך להפעיל. לדוגמה,
  --only functions,firestore.

יצירת אסימון אימות (לאמולטור אירוח בלבד)

אם תהליכי העבודה של השילוב המתמשך מסתמכים על Firebase Hosting , תצטרכו להתחבר באמצעות אסימון כדי להריץ את firebase emulators:exec. לא צריך להתחבר לאף אחד מהמכשירים האחרים.

הערה: אם הגדרתם אירוח ב-firebase.json אבל אתם לא צריכים אותו בהגדרות הבדיקה של ה-CI, תוכלו להשתמש בדגל --only כדי להעביר את הערך emulators:start או emulators:exec כדי לכלול רק את הסימולטורים שאתם צריכים.

כדי ליצור אסימון, מריצים את הפקודה firebase login:ci בסביבה המקומית. לא מומלץ לבצע את הפעולה הזו ממערכת CI. פועלים לפי ההוראות לביצוע אימות. צריך לבצע את השלב הזה רק פעם אחת לכל פרויקט, כי האסימון יהיה תקף בכל גרסאות ה-build. צריך להתייחס לאסימון כמו לסיסמה, ולוודא שהוא נשמר בסודיות.

אם סביבת ה-CI מאפשרת לציין משתני סביבה שאפשר להשתמש בהם בסקריפטים ל-build, פשוט יוצרים משתנה סביבה בשם FIREBASE_TOKEN, והערך הוא המחרוזת של אסימון הגישה. ה-CLI של Firebase יזהה באופן אוטומטי את משתנה הסביבה FIREBASE_TOKEN והמכונות הווירטואליות יתחילו לפעול כמו שצריך.

כחלופה אחרונה, אפשר פשוט לכלול את הטוקן בסקריפט ה-build, אבל חשוב לוודא שלצדדים לא מהימנים אין גישה. לגישה הזו עם קידוד מובנה, אפשר להוסיף את הערך --token "YOUR_TOKEN_STRING_HERE" לפקודה firebase emulators:exec.

שימוש ב-API ל-REST של Emulator Hub

הצגת רשימה של אמולטורים שפועלים

כדי לקבל רשימה של המהדמנים שפועלים כרגע, שולחים בקשת GET לנקודת הקצה /emulators של Emulator Hub.

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 של Emulator Hub.

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
}

שילובים של SDK למהדמרים

בטבלאות שבקטע הזה מצוינים האמולטורים שנתמכים ב-SDK ללקוח וב-Admin SDK. עתידי: המשמעות היא שאנחנו מתכננים תמיכה באמולטורים, אבל היא עדיין לא זמינה.

זמינות של SDK ללקוחות

	Android	פלטפורמות של Apple	אתר	ממשק המשתמש של Firebase Android	ממשק המשתמש של Firebase iOS	ממשק המשתמש של Firebase אינטרנט
Realtime Database	19.4.0	7.2.0	8.0.0	6.4.0	עתיד	לא רלוונטי
Cloud Firestore	21.6.0	7.2.0	8.0.0	6.4.0	עתיד	לא רלוונטי
Authentication	20.0.0	7.0.0	8.0.0	7.0.0	עתיד	4.7.2
Cloud Storage for Firebase	20.0.0	8.0.0	8.4.0	7.0.0	11.0.0	לא רלוונטי
Cloud Functions	19.1.0	7.2.0	8.0.0	לא רלוונטי	לא זמין	לא זמין
Hosting	לא זמין	לא זמין	לא זמין	לא זמין	לא זמין	לא זמין
Extensions	לא זמין	לא זמין	לא זמין	לא זמין	לא זמין	לא רלוונטי

הזמינות של Admin SDK

	Node	Java	Python	Go
Realtime Database	8.6.0	6.10.0	2.18.0	עתיד
Cloud Firestore	8.0.0	6.10.0	3.0.0	1.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	לא זמין	לא זמין	לא זמין	לא רלוונטי