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

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

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

הכלי לאמולטור המקומי ב-Firebase מבוסס על אמולציה של מוצרים לפרויקט Firebase אחד.

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

הכלי המקומי לאמולטור תומך באמולציה של פרויקטים אמיתיים ב-Firebase ובפרויקטים דמו.

סוג הפרויקט פיצ'רים שימוש עם אמולטורים
ריאל

פרויקט Firebase אמיתי הוא פרויקט שיצרתם והגדרתם (סביר להניח דרך מסוף Firebase).

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

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

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

הדגמה (דמו)

לפרויקט הדגמה של Firebase אין הגדרת Firebase אמיתית ואין משאבים פעילים. בדרך כלל אפשר לגשת לפרויקטים האלה דרך Codelabs או מדריכים אחרים.

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

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

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

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

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

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

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

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

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

Android, Apple Platform ו-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
}
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);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

ממשק API מודולרי באינטרנט

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

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

ממשק API של מרחב שמות באינטרנט

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

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

ערכות SDK לניהול

ערכות ה-SDK ל-Firebase Admin מתחברים באופן אוטומטי לאמולטור 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.initializeApp({ projectId: "your-project-id" });
משתנה הסביבה
export GCLOUD_PROJECT="your-project-id"

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

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

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

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

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

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

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

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

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

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

טרנזקציות

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

מדדים

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

מגבלות

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

מה השלבים הבאים?