אפשר להתקין ולהגדיר את חבילת הכלים לאמולטור מקומי ב-Firebase בסביבות שונות של אב טיפוס ובדיקה, החל מסשנים חד-פעמיים של אב טיפוס ועד לתהליכי עבודה של שילוב רציף (CI) בקנה מידה של ייצור.
התקנת חבילת הכלים לאמולטור מקומי
לפני שמתקינים את חבילת הכלים לאמולטור, צריך:
כדי להתקין את חבילת האמולטורים:
- מתקינים את Firebase CLI.
אם עדיין לא התקנתם את Firebase CLI, התקינו אותו עכשיו.
כדי להשתמש בכלים לאמולטור, צריך את גרסה 8.14.0 ומעלה של CLI. כדי לבדוק איזו גרסה מותקנת, אפשר להשתמש בפקודה הבאה:
firebase --version
- אם עדיין לא עשיתם את זה, אתם צריכים להפעיל את ספריית העבודה הנוכחית כפרויקט Firebase, ולפעול לפי ההנחיות במסך כדי לציין באילו מוצרים להשתמש:
firebase init
- מגדירים את חבילת האמולטורים. הפקודה הזו מפעילה אשף הגדרה שמאפשר לבחור את האמולטורים הרצויים, להוריד את הקבצים הבינאריים של האמולטורים המתאימים ולהגדיר את היציאות של האמולטורים אם ברירות המחדל לא מתאימות.
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 שהוגדרו בקובץ
|
||||||||||||||
emulators:exec PATH/TO/SCRIPT
|
מריצים את הסקריפט ב-PATH/TO/SCRIPT אחרי שמפעילים את האמולטורים של מוצרי Firebase שהוגדרו ב-
|
השיטה 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 שפועל. אם הערך שצוין ב-
אתם יכולים להורות לאמולטורים לייצא נתונים באופן אוטומטי כשהם נסגרים, באמצעות הדגלים של |
שילוב עם מערכת ה-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 | לא זמין | לא זמין | לא זמין | לא רלוונטי |