שימוש באמולטור Firestore באופן מקומי

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

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

התקנת האמולטור

כדי להתקין את אמולטור Firestore, מתקינים ומעדכנים את ה-CLI של gcloud:

1. מתקינים את ה-CLI של gcloud.

2. כדי לקבל את התכונות העדכניות, צריך לעדכן את ההתקנה של ה-CLI של gcloud:

   gcloud components update
   

הרצת האמולטור

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

   gcloud emulators firestore start
   

   המאמולטור מדפיס את המארח ואת מספר היציאה שבהם הוא פועל.

   כברירת מחדל, האמולטור מנסה להשתמש ב-127.0.0.1:8080. כדי לקשר את האמולטור למארח וליציאה ספציפיים, משתמשים בדגל האופציונלי --host-port ומחליפים את HOST ואת PORT:

   gcloud emulators firestore start --host-port=HOST:PORT
   

2. מקלידים Control + C כדי לעצור את האמולטור. אפשר גם לעצור את האמולטור באמצעות POST לכתובת /shutdown. לדוגמה:

   curl -d '' HOST:PORT/shutdown
   

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

כדי להפעיל את האמולטור במהדורת Enterprise, משתמשים בדגל האופציונלי --edition. הערכים התקינים הם standard ו-enterprise. כברירת מחדל, האמולטור מופעל במהדורת Standard אם לא מציינים את הדגל.

    gcloud emulators firestore start --edition=enterprise

חיבור לאמולטור

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

ספריות לקוח של השרת

כדי לחבר ספריית לקוח של שרת Firestore (C#‎,‏ Go,‏ Java,‏ Node.js,‏ PHP,‏ Python ו-Ruby), צריך להגדיר את משתנה הסביבה FIRESTORE_EMULATOR_HOST. כשמשתנה הסביבה הזה מוגדר, ספריות הלקוח של השרת מתחברות אוטומטית לאמולטור.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

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

בדוגמאות הבאות אפשר לראות איך לקשר את ה-SDK ל-Android, לפלטפורמות של אפל ול-Web לאמולטור של Firestore:

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

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

מחיקת נתוני האמולטור

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

כדי למחוק את כל הנתונים באמולטור, מבצעים פעולת HTTP DELETE מול נקודת הקצה הבאה, מחליפים את HOST ואת PORT במארח ובפורט שבחרתם ומחליפים את PROJECT_ID במזהה הפרויקט שלכם:

http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents

אם האמולטור לא משתמש ב-127.0.0.1:8080, צריך לשנות את המארח והיציאה. הקוד צריך להמתין לאישור REST שהמחיקה הסתיימה או נכשלה.

אפשר לבצע את הפעולה הזו מהמעטפת באמצעות curl:

$ curl -v -X DELETE "http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents"

ההבדלים בין האמולטור של Firestore לבין סביבת הייצור

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

טרנזקציות

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

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

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

מדדים

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

אין תמיכה בחיפוש טקסט

האמולטור לא תומך בשלב search(...).

מגבלות

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