חיבור האפליקציה לאמולטור 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.

הפעלת האמולטור במהדורה ספציפית

האמולטור יופעל במהדורה שצוינה בקטע firestore.edition בקובץ firebase.json. אפשר גם לציין מהדורה בקטע emulators.firestore.edition ב-firebase.json. הערכים התקינים למהדורה הם standard ו-enterprise. אם מציינים את edition בשתי ההגדרות, emulators.firestore.edition מקבל עדיפות.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

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

כדי לקיים אינטראקציה עם 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

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

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"

Cloud Firestore REST API

האמולטור של Cloud Firestore מספק נקודת קצה (endpoint) מסוג REST לאינטראקציה עם מסד הנתונים. כל הקריאות ל-API בארכיטקטורת REST צריכות להתבצע לנקודת הקצה http://localhost:8080/v1.

הנתיב המלא לקריאת REST הוא:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

לדוגמה, כדי להציג את כל המסמכים באוסף users בפרויקט my-project-id, אפשר להשתמש ב-curl:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

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

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

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

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

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

מגבלות

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

מה הלאה?

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