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

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

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

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

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

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

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

כדאי גם לבדוק את ההגדרות של מזהה הפרויקט שספציפיות לפלטפורמה שהגדרתם כשקבעתם את ההגדרות של פרויקטים בפלטפורמות של אפל, ב-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 של האמולטורים, ואין להם השפעה על חלקים אחרים של FirebaseCLI, כמו Emulator Suite UI.

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

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

פקודה תיאור
emulators:start מפעילים את האמולטורים של מוצרי Firebase שהוגדרו ב-firebase.json. תהליכי האמולטור ימשיכו לפעול עד שתפסיקו אותם באופן מפורש. הפעלת הפקודה Calling 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 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 אופציונלי. מריצים את ממשק המשתמש של האמולטור במהלך ההרצה.
--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 מאפשרת לכם לציין משתני סביבה שאפשר להשתמש בהם בסקריפטים של גרסת ה-build, פשוט יוצרים משתנה סביבה בשם FIREBASE_TOKEN, והערך שלו הוא המחרוזת של אסימון הגישה. ממשק Firebase CLI יזהה באופן אוטומטי את משתנה הסביבה FIREBASE_TOKEN והאמולטורים יופעלו בצורה תקינה.

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

שימוש ב-REST API של 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
}

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

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

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

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

זמינות של Client SDK

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