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

כדי לעבוד עם מסדי נתונים המוגדרים כברירת מחדל ומסדי נתונים בעלי שם אינטראקטיבי Emulator Suite UI, בסרגל הכתובות של הדפדפן, יש לעדכן את כתובת ה-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"

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

ב-Production Firestore אין שיטת SDK של פלטפורמה לשטיפת מסד הנתונים, אבל האמולטור Firestore מספק נקודת קצה ל-REST למטרה הזו ספציפית, וניתן לקרוא לה בשלב הגדרה/tearDown של בדיקה, מכיתת בדיקה או מהמעטפת (למשל, עם curl) לפני התחלת הבדיקה. אפשר להשתמש בגישה הזו כחלופה פשוט לכיבוי תהליך האמולטור.

בשיטה מתאימה, מבצעים פעולת HTTP DELETE ומזינים את מזהה הפרויקט ב-Firebase, לדוגמה firestore-emulator-example, למזהה הבא נקודת קצה (endpoint):

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

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

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

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

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

עסקאות

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

מדדים

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

מגבלות

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

מה הלאה?