לפני חיבור האפליקציה שלך לאמולטור Cloud Firestore, ודא שאתה מבין את זרימת העבודה הכוללת של Firebase Local Emulator Suite , ושאתה מתקין ומגדיר את Local Emulator Suite וסוקר את פקודות ה-CLI שלה.
בחר פרויקט Firebase
Firebase Local Emulator Suite מחקה מוצרים עבור פרויקט Firebase יחיד.
כדי לבחור את הפרויקט לשימוש, לפני שתפעיל את האמולטורים, ב-CLI הפעל firebase use בספריית העבודה שלך. לחלופין, אתה יכול להעביר את דגל --project לכל פקודת אמולטור.
Local Emulator Suite תומכת באמולציה של פרויקטים אמיתיים של Firebase ופרויקטי הדגמה .
| סוג פרויקט | מאפיינים | השתמש עם אמולטורים |
|---|---|---|
| אמיתי | פרויקט Firebase אמיתי הוא פרויקט שיצרת והגדרת (ככל הנראה דרך מסוף Firebase). לפרויקטים אמיתיים יש משאבים חיים, כמו מופעי מסד נתונים, דלי אחסון, פונקציות או כל משאב אחר שהגדרת עבור פרויקט Firebase זה. | כשאתה עובד עם פרויקטים אמיתיים של Firebase, אתה יכול להפעיל אמולטורים עבור כל אחד או כל המוצרים הנתמכים. עבור כל מוצר שאתה לא מחקה, האפליקציות והקוד שלך יתקשרו עם המשאב החי (מופע מסד נתונים, דלי אחסון, פונקציה וכו'). |
| הַדגָמָה | לפרויקט הדגמה של Firebase אין תצורת Firebase אמיתית ואין משאבים חיים. פרויקטים אלה נגישים בדרך כלל באמצעות מעבדות קוד או מדריכים אחרים. מזהי פרויקטים עבור פרויקטי הדגמה כוללים את קידומת | כשאתה עובד עם פרויקטי הדגמה של Firebase, האפליקציות והקוד שלך מקיימים אינטראקציה עם אמולטורים בלבד . אם האפליקציה שלך תנסה ליצור אינטראקציה עם משאב שעבורו לא פועל אמולטור, הקוד הזה ייכשל. |
אנו ממליצים להשתמש בפרויקטי הדגמה בכל מקום אפשרי. ההטבות כוללות:
- הגדרה קלה יותר, מכיוון שאתה יכול להפעיל את האמולטורים מבלי ליצור פרויקט Firebase
- בטיחות חזקה יותר, מכיוון שאם הקוד שלך מפעיל בטעות משאבים לא-דמיית (ייצור), אין סיכוי לשינוי נתונים, שימוש וחיוב
- תמיכה במצב לא מקוון טוב יותר, מכיוון שאין צורך לגשת לאינטרנט כדי להוריד את תצורת ה-SDK שלך.
מכשיר את האפליקציה שלך לדבר עם האמולטורים
פלטפורמות אנדרואיד, אפל וערכות פיתוח אינטרנט
הגדר את התצורה בתוך האפליקציה או שיעורי בדיקה לאינטראקציה עם Cloud Firestore באופן הבא.
Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)
firestore.firestoreSettings = firestoreSettings {
isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
.setPersistenceEnabled(false)
.build();
firestore.setFirestoreSettings(settings);
מָהִיר
let settings = Firestore.firestore().settings settings.host = "localhost:8080" settings.isPersistenceEnabled = false settings.isSSLEnabled = false Firestore.firestore().settings = settings
Web version 9
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);Web version 8
// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
db.useEmulator("localhost", 8080);
}אין צורך בהגדרה נוספת כדי לבדוק פונקציות ענן המופעלות על ידי אירועי Firestore באמצעות האמולטור. כאשר האמולטורים של Firestore ו-Cloud Functions פועלים שניהם, הם פועלים באופן אוטומטי יחד.
ערכות SDK לניהול
ערכות ה-SDK של Firebase Admin מתחברות אוטומטית לאמולטור Cloud Firestore כאשר משתנה הסביבה FIRESTORE_EMULATOR_HOST מוגדר:
export FIRESTORE_EMULATOR_HOST="localhost:8080"
אם הקוד שלך פועל בתוך אמולטור Cloud Functions מזהה הפרויקט שלך ותצורה אחרת יוגדרו אוטומטית בעת קריאת initalizeApp .
אם אתה רוצה שקוד ה-SDK של Admin יתחבר לאמולטור משותף הפועל בסביבה אחרת, תצטרך לציין את אותו מזהה פרויקט שהגדרת באמצעות Firebase CLI . אתה יכול להעביר מזהה פרויקט כדי initializeApp ישירות או להגדיר את משתנה הסביבה GCLOUD_PROJECT .
Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
משתנה הסביבה
export GCLOUD_PROJECT="your-project-id"
נקה את מסד הנתונים שלך בין בדיקות
Production Firestore לא מספקת שיטת SDK של פלטפורמה לשטיפת מסד הנתונים, אבל אמולטור Firestore נותן לך נקודת קצה של REST במיוחד למטרה זו, שניתן לקרוא לה משלב הגדרת מסגרת בדיקה/הורדה, ממחלקת בדיקה או מהמעטפת (למשל , עם curl ) לפני תחילת מבחן. אתה יכול להשתמש בגישה זו כחלופה לכיבוי פשוט של תהליך האמולטור.
בשיטה מתאימה, בצע פעולת HTTP DELETE, וספק את מזהה הפרויקט שלך ב-Firebase, למשל firestore-emulator-example , לנקודת הקצה הבאה:
"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"
כמובן, הקוד שלך צריך להמתין לאישור REST שהשטיפה הסתיימה או נכשלה.
אתה יכול לבצע את הפעולה הזו מהמעטפת:
// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"
לאחר שהטמעת שלב כזה, אתה יכול לרצף את הבדיקות שלך ולהפעיל את הפונקציות שלך בביטחון שהנתונים הישנים יימחקו בין ריצות ואתה משתמש בתצורת בדיקה בסיסית חדשה.
ייבוא וייצוא נתונים
מסד הנתונים והאמולטורים של Cloud Storage for Firebase מאפשרים לך לייצא נתונים ממופע אמולטור פועל. הגדר ערכת נתונים בסיסית לשימוש בבדיקות היחידה שלך או בזרימות עבודה מתמשכות של אינטגרציה, ולאחר מכן ייצא אותה לשיתוף בין הצוות.
firebase emulators:export ./dir
בבדיקות, בעת הפעלת האמולטור, ייבא את נתוני הבסיס.
firebase emulators:start --import=./dir
אתה יכול להורות לאמולטור לייצא נתונים בעת כיבוי, או לציין נתיב ייצוא או פשוט להשתמש בנתיב המועבר לדגל --import .
firebase emulators:start --import=./dir --export-on-exit
אפשרויות ייבוא וייצוא נתונים אלה פועלות גם עם הפקודה firebase emulators:exec . למידע נוסף, עיין בהפניה לפקודת האמולטור .
דמיין את פעילות כללי האבטחה
בזמן שאתה עובד דרך אב טיפוס ולולאות בדיקה, אתה יכול להשתמש בכלי הדמיה ודוחות המסופקים על ידי חבילת האימולטור המקומי.
השתמש בצג הבקשות
אמולטור Cloud Firestore מאפשר לך לדמיין בקשות לקוח בממשק המשתמש של Emulator Suite, כולל מעקב אחר הערכה עבור כללי האבטחה של Firebase.
פתח את הכרטיסייה Firestore > בקשות כדי להציג את רצף ההערכה המפורט עבור כל בקשה.
דמיין דוחות הערכות כללים
כאשר אתה מוסיף כללי אבטחה לאב הטיפוס שלך, אתה יכול לנפות אותם עם כלי ניפוי באגים של Local Emulator Suite.
לאחר הפעלת חבילת בדיקות, תוכל לגשת לדוחות כיסוי בדיקה המראים כיצד כל אחד מכללי האבטחה שלך הוערך.
כדי לקבל את הדוחות, שלח שאילתה לנקודת קצה חשופה באמולטור בזמן שהוא פועל. לגרסה ידידותית לדפדפן, השתמש בכתובת האתר הבאה:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html
זה מפרק את הכללים שלך לביטויים ותת-ביטויים שאתה יכול לעבור עליהם עם העכבר לקבלת מידע נוסף, כולל מספר הערכות וערכים שהוחזרו. עבור גרסת ה-JSON הגולמית של נתונים אלה, כלול את כתובת האתר הבאה בשאילתה שלך:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage
כאן, גרסת ה-HTML של הדוח מדגישה הערכות שגורמות שגיאות לא מוגדרות וערך אפס:
כיצד אמולטור Cloud Firestore שונה מהייצור
אמולטור Cloud Firestore מנסה לשכפל נאמנה את התנהגות שירות הייצור עם כמה מגבלות בולטות.
עסקאות
האמולטור אינו מיישם כרגע את כל התנהגות העסקאות שנראתה בייצור. כאשר אתה בודק תכונות הכוללות מספר כתיבה בו-זמנית למסמך אחד, האמולטור עשוי לאט להשלים בקשות כתיבה. במקרים מסוימים, שחרור מנעולים עשוי להימשך עד 30 שניות. שקול להתאים את זמני הבדיקה בהתאם, במידת הצורך.
אינדקסים
האמולטור אינו עוקב אחר אינדקסים מורכבים ובמקום זאת יבצע כל שאילתה חוקית. הקפד לבדוק את האפליקציה שלך מול מופע אמיתי של Cloud Firestore כדי לקבוע אילו אינדקסים תצטרך.
גבולות
האמולטור אינו אוכף את כל המגבלות שנאכפות בייצור. לדוגמה, האמולטור עשוי לאפשר עסקאות שיידחו כגדולות מדי על ידי שירות ההפקה. ודא שאתה מכיר את המגבלות המתועדות ושאתה מעצב את האפליקציה שלך כדי להימנע מהן באופן יזום.
מה הלאה?
- לסט אוסף של סרטונים ודוגמאות מפורטות של הדרכה, עקוב אחר רשימת ההשמעה של Firebase Emulators Training .
- חקור מקרי שימוש מתקדמים הכוללים בדיקות כללי אבטחה ו- Firebase Test SDK: Test Security Rules (Firestore) .
- מכיוון שפונקציות המופעלות הן אינטגרציה טיפוסית עם Cloud Firestore, למד עוד על אמולטור Cloud Functions for Firebase ב- Run functions locally .
לפני חיבור האפליקציה שלך לאמולטור Cloud Firestore, ודא שאתה מבין את זרימת העבודה הכוללת של Firebase Local Emulator Suite , ושאתה מתקין ומגדיר את Local Emulator Suite וסוקר את פקודות ה-CLI שלה.
בחר פרויקט Firebase
Firebase Local Emulator Suite מחקה מוצרים עבור פרויקט Firebase יחיד.
כדי לבחור את הפרויקט לשימוש, לפני שתפעיל את האמולטורים, ב-CLI הפעל firebase use בספריית העבודה שלך. לחלופין, אתה יכול להעביר את דגל --project לכל פקודת אמולטור.
Local Emulator Suite תומכת באמולציה של פרויקטים אמיתיים של Firebase ופרויקטי הדגמה .
| סוג פרויקט | מאפיינים | השתמש עם אמולטורים |
|---|---|---|
| אמיתי | פרויקט Firebase אמיתי הוא פרויקט שיצרת והגדרת (ככל הנראה דרך מסוף Firebase). לפרויקטים אמיתיים יש משאבים חיים, כמו מופעי מסד נתונים, דלי אחסון, פונקציות או כל משאב אחר שהגדרת עבור פרויקט Firebase זה. | כשאתה עובד עם פרויקטים אמיתיים של Firebase, אתה יכול להפעיל אמולטורים עבור כל אחד או כל המוצרים הנתמכים. עבור כל מוצר שאתה לא מחקה, האפליקציות והקוד שלך יתקשרו עם המשאב החי (מופע מסד נתונים, דלי אחסון, פונקציה וכו'). |
| הַדגָמָה | לפרויקט הדגמה של Firebase אין תצורת Firebase אמיתית ואין משאבים חיים. פרויקטים אלה נגישים בדרך כלל באמצעות מעבדות קוד או מדריכים אחרים. מזהי פרויקטים עבור פרויקטי הדגמה כוללים את קידומת | כשאתה עובד עם פרויקטי הדגמה של Firebase, האפליקציות והקוד שלך מקיימים אינטראקציה עם אמולטורים בלבד . אם האפליקציה שלך תנסה ליצור אינטראקציה עם משאב שעבורו לא פועל אמולטור, הקוד הזה ייכשל. |
אנו ממליצים להשתמש בפרויקטי הדגמה בכל מקום אפשרי. ההטבות כוללות:
- הגדרה קלה יותר, מכיוון שאתה יכול להפעיל את האמולטורים מבלי ליצור פרויקט Firebase
- בטיחות חזקה יותר, מכיוון שאם הקוד שלך מפעיל בטעות משאבים לא-דמיית (ייצור), אין סיכוי לשינוי נתונים, שימוש וחיוב
- תמיכה במצב לא מקוון טוב יותר, מכיוון שאין צורך לגשת לאינטרנט כדי להוריד את תצורת ה-SDK שלך.
מכשיר את האפליקציה שלך לדבר עם האמולטורים
פלטפורמות אנדרואיד, אפל וערכות פיתוח אינטרנט
הגדר את התצורה בתוך האפליקציה או שיעורי בדיקה לאינטראקציה עם Cloud Firestore באופן הבא.
Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)
firestore.firestoreSettings = firestoreSettings {
isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
.setPersistenceEnabled(false)
.build();
firestore.setFirestoreSettings(settings);
מָהִיר
let settings = Firestore.firestore().settings settings.host = "localhost:8080" settings.isPersistenceEnabled = false settings.isSSLEnabled = false Firestore.firestore().settings = settings
Web version 9
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);Web version 8
// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
db.useEmulator("localhost", 8080);
}אין צורך בהגדרה נוספת כדי לבדוק פונקציות ענן המופעלות על ידי אירועי Firestore באמצעות האמולטור. כאשר האמולטורים של Firestore ו-Cloud Functions פועלים שניהם, הם פועלים באופן אוטומטי יחד.
ערכות SDK לניהול
ערכות ה-SDK של Firebase Admin מתחברות אוטומטית לאמולטור Cloud Firestore כאשר משתנה הסביבה FIRESTORE_EMULATOR_HOST מוגדר:
export FIRESTORE_EMULATOR_HOST="localhost:8080"
אם הקוד שלך פועל בתוך אמולטור Cloud Functions מזהה הפרויקט שלך ותצורה אחרת יוגדרו אוטומטית בעת קריאת initalizeApp .
אם אתה רוצה שקוד ה-SDK של Admin יתחבר לאמולטור משותף הפועל בסביבה אחרת, תצטרך לציין את אותו מזהה פרויקט שהגדרת באמצעות Firebase CLI . אתה יכול להעביר מזהה פרויקט כדי initializeApp ישירות או להגדיר את משתנה הסביבה GCLOUD_PROJECT .
Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
משתנה הסביבה
export GCLOUD_PROJECT="your-project-id"
נקה את מסד הנתונים שלך בין בדיקות
Production Firestore לא מספקת שיטת SDK של פלטפורמה לשטיפת מסד הנתונים, אבל אמולטור Firestore נותן לך נקודת קצה של REST במיוחד למטרה זו, שניתן לקרוא לה משלב הגדרת מסגרת בדיקה/הורדה, ממחלקת בדיקה או מהמעטפת (למשל , עם curl ) לפני תחילת מבחן. אתה יכול להשתמש בגישה זו כחלופה לכיבוי פשוט של תהליך האמולטור.
בשיטה מתאימה, בצע פעולת HTTP DELETE, וספק את מזהה הפרויקט שלך ב-Firebase, למשל firestore-emulator-example , לנקודת הקצה הבאה:
"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"
כמובן, הקוד שלך צריך להמתין לאישור REST שהשטיפה הסתיימה או נכשלה.
אתה יכול לבצע את הפעולה הזו מהמעטפת:
// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"
לאחר שהטמעת שלב כזה, אתה יכול לרצף את הבדיקות שלך ולהפעיל את הפונקציות שלך בביטחון שהנתונים הישנים יימחקו בין ריצות ואתה משתמש בתצורת בדיקה בסיסית חדשה.
ייבוא וייצוא נתונים
מסד הנתונים והאמולטורים של Cloud Storage for Firebase מאפשרים לך לייצא נתונים ממופע אמולטור פועל. הגדר ערכת נתונים בסיסית לשימוש בבדיקות היחידה שלך או בזרימות עבודה מתמשכות של אינטגרציה, ולאחר מכן ייצא אותה לשיתוף בין הצוות.
firebase emulators:export ./dir
בבדיקות, בעת הפעלת האמולטור, ייבא את נתוני הבסיס.
firebase emulators:start --import=./dir
אתה יכול להורות לאמולטור לייצא נתונים בעת כיבוי, או לציין נתיב ייצוא או פשוט להשתמש בנתיב המועבר לדגל --import .
firebase emulators:start --import=./dir --export-on-exit
אפשרויות ייבוא וייצוא נתונים אלה פועלות גם עם הפקודה firebase emulators:exec . למידע נוסף, עיין בהפניה לפקודת האמולטור .
דמיין את פעילות כללי האבטחה
בזמן שאתה עובד דרך אב טיפוס ולולאות בדיקה, אתה יכול להשתמש בכלי הדמיה ודוחות המסופקים על ידי חבילת האימולטור המקומי.
השתמש בצג הבקשות
אמולטור Cloud Firestore מאפשר לך לדמיין בקשות לקוח בממשק המשתמש של Emulator Suite, כולל מעקב אחר הערכה עבור כללי האבטחה של Firebase.
פתח את הכרטיסייה Firestore > בקשות כדי להציג את רצף ההערכה המפורט עבור כל בקשה.
דמיין דוחות הערכות כללים
כאשר אתה מוסיף כללי אבטחה לאב הטיפוס שלך, אתה יכול לנפות אותם עם כלי ניפוי באגים של Local Emulator Suite.
לאחר הפעלת חבילת בדיקות, תוכל לגשת לדוחות כיסוי בדיקה המראים כיצד כל אחד מכללי האבטחה שלך הוערך.
כדי לקבל את הדוחות, שלח שאילתה לנקודת קצה חשופה באמולטור בזמן שהוא פועל. לגרסה ידידותית לדפדפן, השתמש בכתובת האתר הבאה:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html
זה מפרק את הכללים שלך לביטויים ותת-ביטויים שאתה יכול לעבור עליהם עם העכבר לקבלת מידע נוסף, כולל מספר הערכות וערכים שהוחזרו. עבור גרסת ה-JSON הגולמית של נתונים אלה, כלול את כתובת האתר הבאה בשאילתה שלך:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage
כאן, גרסת ה-HTML של הדוח מדגישה הערכות שגורמות שגיאות לא מוגדרות וערך אפס:
כיצד אמולטור Cloud Firestore שונה מהייצור
אמולטור Cloud Firestore מנסה לשכפל נאמנה את התנהגות שירות הייצור עם כמה מגבלות בולטות.
עסקאות
האמולטור אינו מיישם כרגע את כל התנהגות העסקאות שנראתה בייצור. כאשר אתה בודק תכונות הכוללות מספר כתיבה בו-זמנית למסמך אחד, האמולטור עשוי לאט להשלים בקשות כתיבה. במקרים מסוימים, שחרור מנעולים עשוי להימשך עד 30 שניות. שקול להתאים את זמני הבדיקה בהתאם, במידת הצורך.
אינדקסים
האמולטור אינו עוקב אחר אינדקסים מורכבים ובמקום זאת יבצע כל שאילתה חוקית. הקפד לבדוק את האפליקציה שלך מול מופע אמיתי של Cloud Firestore כדי לקבוע אילו אינדקסים תצטרך.
גבולות
האמולטור אינו אוכף את כל המגבלות שנאכפות בייצור. לדוגמה, האמולטור עשוי לאפשר עסקאות שיידחו כגדולות מדי על ידי שירות ההפקה. ודא שאתה מכיר את המגבלות המתועדות ושאתה מעצב את האפליקציה שלך כדי להימנע מהן באופן יזום.
מה הלאה?
- לסט אוסף של סרטונים ודוגמאות מפורטות של הדרכה, עקוב אחר רשימת ההשמעה של Firebase Emulators Training .
- חקור מקרי שימוש מתקדמים הכוללים בדיקות כללי אבטחה ו- Firebase Test SDK: Test Security Rules (Firestore) .
- מכיוון שפונקציות המופעלות הן אינטגרציה טיפוסית עם Cloud Firestore, למד עוד על אמולטור Cloud Functions for Firebase ב- Run functions locally .