בדיקת מצב 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

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

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

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

מדדים

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

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

gcloud emulators firestore start --database-mode=datastore-mode --require-indexes --index-file=./index.yaml

מידע נוסף על הפורמט של index-file זמין במאמר הגדרת אינדקסים של Datastore באמצעות index.yaml.

מגבלות

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

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