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

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

מזהי פרויקטים של פרויקטים לדוגמה כוללים את הקידומת demo-.

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

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

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

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

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

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

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

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

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

מגדירים את ההגדרות או את כיתות הבדיקה באפליקציה כך שיתקשרו עם Cloud Firestore באופן הבא. שימו לב שבדוגמאות הבאות, קוד האפליקציה מתחבר למסד הנתונים של הפרויקט שמוגדר כברירת מחדל. דוגמאות לשימוש במסדי נתונים נוספים של 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
}
EmulatorSuite.kt
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);
EmulatorSuite.java
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web

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

Web

// 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.

SDK של Node.js Admin
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 כדי לראות את רצף ההערכה המפורט של כל בקשה.

מוניטור הבקשות של Firestore Emulator שמוצגות בו הערכות של כללי האבטחה

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

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

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

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

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

עסקאות

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

מדדים

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

מגבלות

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

מה הלאה?