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

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

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

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

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

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

  1. מתקינים את ה-CLI של Firebase. אם עדיין לא התקנתם את 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 במצב ה-GRU

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

פקודה תיאור
אמולטורים init הפעלת אשף אתחול של אמולטור. צריך לזהות אמולטורים שצריך להתקין, ולבחור את ההגדרות ליציאת האמולטור. init emulators לא הרסנית; אם בוחרים לקבל את ברירות המחדל, ההגדרה הנוכחית של האמולטור תישמר.

הגדרת יציאות

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

מכונה וירטואלית יציאת ברירת מחדל
Authentication 9099
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 של ספריית בדיקות יחידה (unit testing).
  • הדגל --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, ייתכן גודל הערימה המקסימלי של Java ל-4GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

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

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

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

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

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

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

אפשר לייצא נתונים מהמקורות הבאים: Authentication, Cloud Firestore, Realtime Database אמולטורים של Cloud Storage for Firebase לשימוש כנתוני בסיס משותפים שניתן לשתף הוגדרה. ניתן לייבא את קבוצות הנתונים האלה באמצעות הדגל --import, שתוארו למעלה.

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

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

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

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

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

שילובי 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

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