בדיקת מצב Datastore באמצעות אמולטור Firestore

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

משתמשים ב-gcloud emulators firestore עם --database-mode=datastore-mode כדי לבדוק את ההתנהגות של Firestore במצב Datastore.

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

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

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

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

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

    gcloud components update

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

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

    gcloud emulators firestore start --database-mode=datastore-mode

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

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

    gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT

  2. משתמשים במקש הקיצור Control + C כדי לעצור את האמולטור.

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

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

export DATASTORE_EMULATOR_HOST="HOST:PORT"

ייבוא ישויות לאמולטור

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

יש שתי דרכים לייבא ישויות לאמולטור. האפשרות הראשונה היא להוסיף את הדגל import-data לפקודת ההפעלה של האמולטור. השיטה השנייה היא לשלוח בקשת ייבוא POST לאמולטור. אפשר להשתמש ב-curl או בכלי דומה. כדאי לעיין בדוגמאות הבאות.

פרוטוקול

‫
curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
משנים את localhost:8080 אם האמולטור משתמש ביציאה אחרת.

CLI Flag

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY

where:

  • ‫[PROJECT_ID] הוא מזהה הפרויקט.

  • ‫[DATABASE] הוא הנתיב למסד הנתונים. לדוגמה, פרויקט עם מסד נתונים שמוגדר כברירת מחדל ייראה כך:

    {"database":"projects/myProject/databases/"}

  • ‫[EXPORT_DIRECTORY] הוא הנתיב לקובץ overall_export_metadata של קובצי הייצוא של הישות. לדוגמה:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

ייצוא ישויות באמולטור

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

יש שתי דרכים לייצא ישויות מהאמולטור. האפשרות הראשונה היא להוסיף את הדגל export-on-exit לפקודת ההפעלה של האמולטור. השיטה השנייה היא לשלוח בקשת ייצוא של POST לאמולטור. אפשר להשתמש ב-curl או בכלי דומה. כדאי לעיין בדוגמאות הבאות.

פרוטוקול

‫
curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'
משנים את localhost:8080 אם האמולטור משתמש ביציאה אחרת.

CLI Flag

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

where:

  • ‫[PROJECT_ID] הוא מזהה הפרויקט.

  • ‫[DATABASE_PATH] הוא הנתיב למסד הנתונים. לדוגמה, פרויקט עם מסד נתונים שמוגדר כברירת מחדל ייראה כך:

    {"database":"projects/myProject/databases/"}

  • ‫[EXPORT_DIRECTORY] מציין את הספרייה שבה האמולטור שומר את קובצי ייצוא הישויות. הספרייה הזו לא יכולה להכיל כבר קבוצה של קובצי ייצוא של ישויות. לדוגמה:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

שמירת נתונים באמולטור

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

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY

איפוס נתוני האמולטור

אמולטור Firestore כולל נקודת קצה (endpoint) של REST לאיפוס כל הנתונים באמולטור. אפשר להשתמש בנקודת הקצה הזו כדי לנקות נתונים בין בדיקות בלי לכבות את האמולטור.

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

http://HOST:PORT/reset

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

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

$ curl -X POST "http://HOST:PORT/reset"

ההבדלים בין האמולטור לבין הסביבה הפעילה

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

בו-זמניות ועקביות

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

טרנזקציות

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

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

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

מדדים

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

מגבלות

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

המאמרים הבאים