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

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

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

‫Firebase Local Emulator Suite מדמה מוצרים לפרויקט Firebase יחיד.

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

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

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

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

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

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

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

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

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

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

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

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

export GCLOUD_PROJECT="your-project-id"

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

ב-Firestore בסביבת הייצור אין שיטה בערכת ה-SDK של הפלטפורמה לניקוי מסד הנתונים, אבל באמולטור של Firestore יש נקודת קצה של REST שנועדה במיוחד למטרה הזו. אפשר לקרוא לה משלב setup/tearDown של מסגרת בדיקה, ממחלקת בדיקה או מהמעטפת (למשל, באמצעות 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.

שימוש בכלי למעקב אחרי בקשות

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

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

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

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

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

כדי לקבל את הדוחות, צריך להריץ שאילתה על נקודת קצה (endpoint) שחשופה באמולטור. כדי להשתמש בגרסה שמתאימה לדפדפן, משתמשים בכתובת ה-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 Emulator מנסה לשכפל באופן מדויק את ההתנהגות של שירות הייצור, עם כמה מגבלות בולטות.

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

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

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

עסקאות

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

מדדים

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

מגבלות

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

מה הלאה?

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