חיבור האפליקציה לאמולטור Cloud Firestore

לפני שמחברים את האפליקציה למהדמ של Cloud Firestore, חשוב לוודא שמבינים את תהליך העבודה הכללי של Firebase Local Emulator Suite, ומתקינים ומגדירים את Local Emulator Suite ובודקים את פקודות ה-CLI שלו.

בחירת פרויקט ב-Firebase

ה-Firebase Local Emulator Suite מאפשר לדמות מוצרים לפרויקט Firebase יחיד.

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

Local Emulator Suite תומך בהדמיה של פרויקטים אמיתיים ופרויקטים דמוניים ב-Firebase.

מומלץ להשתמש בפרויקטים לדוגמה כשהדבר אפשרי. ההטבות כוללות:

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

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

בזמן ההפעלה, אמולטור Cloud Firestore יוצר מסד נתונים שמוגדר כברירת מחדל ומסד נתונים בעל שם לכל הגדרת firestore בקובץ firebase.json.

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

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

• לדוגמה, כדי לעיין בנתונים במכונה שמוגדרת כברירת מחדל, מעדכנים את כתובת ה-URL ל-localhost:4000/firestore/default/data
• כדי לעיין במכונה בשם ecommerce, מעדכנים את הגרסה ל-localhost:4000/firestore/ecommerce/data.

Android, פלטפורמות של Apple ו-SDK לאינטרנט

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

// 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
}
EmulatorSuite.kt

// 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);
EmulatorSuite.java

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

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

Admin SDK שניות

ה-Firebase Admin SDK מתחברים באופן אוטומטי למהדמטור Cloud Firestore כשמגדירים את משתנה הסביבה FIRESTORE_EMULATOR_HOST:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

אם הקוד פועל בתוך המהדר של Cloud Functions, מזהה הפרויקט והגדרות אחרות מוגדרים באופן אוטומטי בזמן הקריאה ל-initializeApp.

אם רוצים שהקוד Admin SDK יתחבר למהדרל משותף שפועל בסביבה אחרת, צריך לציין את אותו מזהה פרויקט שהגדרתם באמצעות CLI של Firebase. אפשר להעביר מזהה פרויקט ישירות אל initializeApp או להגדיר את משתנה הסביבה GCLOUD_PROJECT.

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

ניקוי מסד הנתונים בין בדיקות

ב-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. מידע נוסף זמין במאמר העזרה בנושא פקודות של המהדר‬.

הצגה חזותית של הפעילות של כללי האבטחה

כשאתם עובדים על אב טיפוס ועל לולאות בדיקה, אתם יכולים להשתמש בכלים להצגה חזותית ובדוחות שסופקו על ידי Local Emulator Suite.

שימוש ב-Requests Monitor

באמצעות המהדר של Cloud Firestore אפשר להציג גרפית את בקשות הלקוח ב-Emulator Suite UI, כולל מעקב אחר הערכה של Firebase Security Rules.

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

הצגה חזותית של דוחות הערכות של כללים

כשאתם מוסיפים כללי אבטחה לאב טיפוס, אתם יכולים לנפות באגים באמצעות כלים לניפוי באגים של Local Emulator Suite.

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

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

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

הפעולה הזו מפרקת את הכללים לביטויים ולביטויים משנה, שאפשר להעביר מעליהם את העכבר כדי לקבל מידע נוסף, כולל מספר הבדיקות והערכים שהוחזרו. כדי לקבל את גרסת ה-JSON הגולמי של הנתונים האלה, צריך לכלול את כתובת ה-URL הבאה בשאילתה:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

כאן, בגרסה ה-HTML של הדוח מודגשות הערכות שמניבות שגיאות של ערך לא מוגדר וערך null:

ההבדל בין המהדורה לבדיקה של Cloud Firestore לבין המהדורה בסביבת הייצור

המהדר של Cloud Firestore מנסה לשחזר בצורה נאמנה את ההתנהגות של שירות הייצור, עם כמה מגבלות משמעותיות.

תמיכה במספר מסדי נתונים ב-Cloud Firestore

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

עם זאת, הסימולטור עצמו יוצר מסד נתונים בעל שם על סמך ההגדרות בקובץ firebase.json, ובעקיפין בתגובה לקריאות ל-SDK או ל-REST API.

עסקאות

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

מדדים

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

מגבלות

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

מה הלאה?

• כדי לקבל קבוצה נבחרת של סרטונים ודוגמאות מפורטות לשימוש, אפשר לעיין בפלייליסט ההדרכה של מכונות הווירטואליות של Firebase.
• תרחישים מתקדמים לדוגמה שכוללים בדיקה של כללי אבטחה ו-Firebase Test SDK: בדיקת כללי אבטחה (Firestore).
• פונקציות מופעלות הן שילוב טיפוסי עם Cloud Firestore, ולכן מומלץ לקרוא מידע נוסף על המהדר של Cloud Functions for Firebase במאמר הרצת פונקציות באופן מקומי.