התקנה, הגדרה ושילוב של Local Emulator Suite

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

התקנת חבילת הכלים לאמולטור מקומי

לפני שמתקינים את חבילת הכלים לאמולטור, צריך:

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

כדי להתקין את חבילת האמולטורים:

  1. מתקינים את Firebase CLI. אם עדיין לא התקנתם את Firebase CLI, התקינו אותו עכשיו. כדי להשתמש בכלים לאמולטור, צריך את גרסה 8.14.0 ומעלה של 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 יפעלו עם אבטחת נתונים פתוחים.

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

כדאי גם לבדוק את ההגדרות של מזהה הפרויקט הספציפיות לפלטפורמה שקבעתם כשהגדרתם את הפרויקטים לפלטפורמות של 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 heap space, אתם יכולים להגדיל את הגודל המקסימלי של Java heap ל-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 כדי להפעיל ניפוי באגים של פונקציות באמצעות נקודות עצירה (breakpoint) ביציאה שצוינה (או ביציאת ברירת המחדל 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 אופציונלי. משתמשים באפשרות הזו עם האמולטור Cloud Functions כדי להפעיל ניפוי באגים של פונקציות באמצעות נקודות עצירה (breakpoint) ביציאה שצוינה (או ביציאת ברירת המחדל 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 אופציונלי. מריצים את ממשק המשתמש של האמולטור במהלך ההפעלה.
--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. פועלים לפי ההוראות לאימות. צריך לבצע את השלב הזה רק פעם אחת בכל פרויקט, כי האסימון יהיה תקף בכל גרסאות ה-build. צריך להתייחס לטוקן כמו לסיסמה, ולוודא שהוא נשמר בסוד.

אם סביבת ה-CI מאפשרת לציין משתני סביבה שאפשר להשתמש בהם בסקריפטים של ה-build, פשוט יוצרים משתנה סביבה בשם FIREBASE_TOKEN, כשהערך הוא המחרוזת של טוקן הגישה. ‫Firebase CLI יזהה באופן אוטומטי את משתנה הסביבה 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 לנקודת הקצה (endpoint) /functions/disableBackgroundTriggers של Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

התוצאה תהיה אובייקט JSON שמפרט את המצב הנוכחי.

{
  "enabled": false
}

כדי להפעיל טריגרים של פונקציות מקומיות אחרי שהם הושבתו, שולחים בקשת PUT לנקודת הקצה (endpoint) /functions/enableBackgroundTriggers של Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

התוצאה תהיה אובייקט JSON שמפרט את המצב הנוכחי.

{
  "enabled": true
}

שילובים של SDK באמולטור

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

זמינות של ערכת SDK ללקוח

Android פלטפורמות של אפל אתר Firebase UI
Android
Firebase UI
iOS
Firebase UI
אינטרנט
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

צומת 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 לא זמין לא זמין לא זמין לא רלוונטי