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

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

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

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

• ‫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 יפעלו עם אבטחת נתונים פתוחה.

הגדרת יציאות

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

הגדרת מזהה הפרויקט

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

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

‫Local Emulator Suite מציג אזהרות כשהוא מזהה כמה מזהי פרויקטים בסביבה, אבל אפשר לשנות את ההתנהגות הזו על ידי הגדרת המפתח singleProjectMode לערך false ב-firebase.json.

אפשר לבדוק אם יש אי התאמות בהצהרות על מזהי פרויקטים במיקומים הבאים:

• פרויקט ברירת המחדל בשורת הפקודה. כברירת מחדל, מזהה הפרויקט יילקח בהפעלה מהפרויקט שנבחר באמצעות firebase init או firebase use. כדי לראות את רשימת הפרויקטים (ולבדוק איזה פרויקט נבחר), משתמשים בפקודה firebase projects:list.
• בדיקות יחידה של כללים. מזהה הפרויקט מצוין לעיתים קרובות בקריאות לשיטות של ספריית הבדיקות של יחידות הכללים initializeTestEnvironment או initializeTestApp.
• הדגל --project בשורת הפקודה. העברת הדגל Firebase של --project CLI מבטלת את פרויקט ברירת המחדל. צריך לוודא שערך הדגל תואם למזהה הפרויקט בבדיקות היחידה ובאתחול האפליקציה.

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

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

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

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

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

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

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

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

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

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

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

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

זמינות של Client SDK

הזמינות של Admin SDK