ייבוא וייצוא של נתונים

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

בדף הזה מוסבר איך לייצא ולייבא מסמכי Cloud Firestore באמצעות שירות הייצוא והייבוא המנוהל ו-Cloud Storage. שירות הייצוא והייבוא המנוהל של Cloud Firestore זמין דרך כלי שורת הפקודה gcloud ודרך ה-API של Cloud Firestore (REST, ‏ RPC).

לפני שמתחילים

כדי להשתמש בשירות המנוהל לייצוא ולייבוא, צריך לבצע את הפעולות הבאות:

1. הפעלת החיוב בפרויקט ב-Google Cloud רק בפרויקטים ב-Google Cloud שמופעל בהם חיוב אפשר להשתמש בפונקציונליות של ייצוא וייבוא.
2. יוצרים קטגוריה של Cloud Storage לפרויקט במיקום שקרוב למיקום של מסד הנתונים ב-Cloud Firestore. אי אפשר להשתמש בקטגוריה שבה מופעלת התכונה "מגיש הבקשה משלם" או בקטגוריית Rapid לצורך פעולות ייצוא וייבוא.

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

   • ‫תפקידים ב-Cloud Firestore: Owner,‏ Cloud Datastore Owner או Cloud Datastore Import Export Admin

   • ‫Cloud Storage תפקידים: Owner או Storage Admin

הרשאות של סוכן שירות

פעולות הייצוא והייבוא משתמשות בסוכן שירות של Cloud Firestore כדי לאשר פעולות של Cloud Storage. השם של סוכן השירות Cloud Firestore מורכב לפי המוסכמה הבאה:

סוכן שירות של Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

למידע נוסף על סוכני שירות, קראו את המאמר סוכני שירות.

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

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

הקצאת תפקידים לסוכן השירות

אפשר להשתמש בכלי שורת הפקודה gsutil כדי להקצות את אחד מהתפקידים הבאים. לדוגמה, כדי להקצות את התפקיד "אדמין של Storage" לסוכן השירות Cloud Firestore, מריצים את הפקודה הבאה:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

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

אפשר גם להקצות את התפקיד הזה באמצעות מסוף Google Cloud.

הצגת השם של סוכן השירות

אפשר לראות את החשבון שבו משתמשות פעולות הייבוא והייצוא כדי לאשר בקשות מהדף Import/Export במסוף Google Cloud. אתם יכולים גם לראות אם מסד הנתונים משתמש בסוכן השירות של Cloud Firestore או בחשבון השירות הקודם של App Engine.

1. החשבון המורשה מופיע לצד התווית משימות הייבוא/הייצוא פועלות בתור.

סוכן השירות צריך את התפקיד Storage Admin בקטגוריה Cloud Storage כדי להשתמש בה לפעולת הייצוא או הייבוא.

הגדרת gcloud לפרויקט

אפשר להתחיל פעולות ייבוא וייצוא דרך מסוף Google Cloud או דרך כלי שורת הפקודה gcloud. כדי להשתמש ב-gcloud, מגדירים את כלי שורת הפקודה ומתחברים לפרויקט באחת מהדרכים הבאות:

• גישה אל gcloud ממסוף Google Cloud באמצעות Cloud Shell.

  התחלה Cloud Shell

  מוודאים ש-gcloud מוגדר לפרויקט הנכון:

  gcloud config set project [PROJECT_ID]
  

• מתקינים ומפעילים את Google Cloud SDK.

ייבוא נתונים

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

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

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

• אם מסמך במסד הנתונים לא מושפע מהייבוא, הוא יישאר במסד הנתונים אחרי הייבוא.

• שם הקובץ .overall_export_metadata צריך להיות זהה לשם של תיקיית ההורה שלו:

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  אם אתם מעבירים או מעתיקים את קובצי הפלט של הייצוא, הקפידו לשמור על אותו שם קובץ של PARENT_FOLDER_NAME ו-.overall_export_metadata.

• ייבוא למסד נתונים של Cloud Firestore מייצוא עם אוספי משנה נכשל, כי אוספי משנה לא נתמכים ב-Cloud Firestore.

• ייבוא למסד נתונים של Firestore Standard Edition מייצוא עם סוגי BSON נכשל, כי סוגי BSON לא נתמכים ב-Firestore Standard Edition.

• אי אפשר לייבא למסד נתונים של Cloud Firestore נתונים ממרחבי שמות שאינם ברירת מחדל (Datastore API).

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

ייבוא כל המסמכים מקובץ ייצוא

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

ייבוא אוספים ספציפיים

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
  --database=[DATABASE]

ייבוא מייצוא עם נתוני PITR

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

ייצוא נתונים

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

ייצוא כל המסמכים

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

ייצוא אוספים ספציפיים

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

ייצוא מחותמת זמן של PITR

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

פעולת הייצוא של PITR תומכת בכל המסננים, כולל ייצוא של כל המסמכים וייצוא של אוספים ספציפיים.

לפני שמייצאים נתוני PITR, חשוב לשים לב לנקודות הבאות:

• ציינו את חותמת הזמן בפורמט RFC 3339. לדוגמה, 2020-09-01T23:59:30.234233Z.
• חשוב לוודא שחותמת הזמן שציינתם היא חותמת זמן של דקה שלמה בשבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, נוצרת שגיאה.
• לא תחויבו על ייצוא PITR שנכשל.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

ניהול פעולות ייצוא וייבוא

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

שמות הפעולות מתחילים בקידומת projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, לדוגמה:

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

עם זאת, אפשר להשמיט את הקידומת כשמציינים שם של פעולה בפקודות describe,‏ cancel ו-delete.

הצגת רשימה של כל פעולות הייצוא והייבוא

gcloud firestore operations list

בדיקת סטטוס הפעולה

gcloud firestore operations describe [OPERATION_NAME]

הערכת זמן הסיום

בקשה לסטטוס של פעולה ממושכת מחזירה את המדדים workEstimated ו-workCompleted. כל אחד מהמדדים האלה מוחזר גם במספר הבייטים וגם במספר הישויות:

• השדה workEstimated מציג את המספר הכולל המשוער של בייטים ומסמכים שפעולה תעבד. יכול להיות שהמדד הזה לא יופיע ב-Cloud Firestore אם המערכת לא יכולה ליצור אומדן.

• ‫workCompleted מציג את מספר הבייטים והמסמכים שעובדו עד עכשיו. אחרי שהפעולה מסתיימת, הערך מציג את המספר הכולל של הבייטים והמסמכים שעובדו בפועל, שיכול להיות גדול מהערך של workEstimated.

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

ביטול פעולה

gcloud firestore operations cancel [OPERATION_NAME]

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

מחיקת פעולה

כדי להסיר פעולה מרשימת הפעולות האחרונות, משתמשים בפקודה gcloud firestore operations delete. הפקודה הזו לא תמחק קובצי ייצוא מ-Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

חיוב ותמחור של פעולות ייצוא וייבוא

כדי להשתמש בשירות המנוהל לייצוא ולייבוא, צריך להפעיל את החיוב בפרויקט ב-Google Cloud.

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

קובצי הפלט שמאוחסנים ב-Cloud Storage נכללים בעלויות אחסון הנתונים ב-Cloud Storage.

פעולות ייצוא או ייבוא לא יפעילו את ההתראות של תקציב Google Cloud עד לסיום הפעולות. פעולות ייצוא וייבוא לא ישפיעו על השימוש שמוצג בקטע Usage במסוף.

צפייה בעלויות הייצוא והייבוא

פעולות הייצוא והייבוא מחילות את התווית goog-firestoremanaged:exportimport על פעולות שמחויבות. בדף דוחות חיוב ב-Cloud, אתם יכולים להשתמש בתווית הזו כדי לראות את העלויות שקשורות לפעולות הייבוא והייצוא:

ייצוא אל BigQuery

אפשר לטעון נתונים מייצוא של Cloud Firestore אל BigQuery, אבל רק אם ציינתם מסנן collection-ids. טעינת נתונים מייצוא של Cloud Firestore

כשאתם טוענים נתונים מ-Cloud Firestore ל-BigQuery, סוגי הנתונים של BSON מיוצגים באמצעות סוג הנתונים של STRING.

מגבלה של BigQuery עמודות

ב-BigQuery יש מגבלה של 10,000 עמודות לכל טבלה. פעולות הייצוא של Cloud Firestore יוצרות סכימת טבלה ב-BigQuery לכל אוסף. בסכימה הזו, כל שם שדה ייחודי באוסף הופך לעמודה בסכימה.

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

פורמט הייצוא וקובצי המטא-נתונים

הפלט של ייצוא מנוהל משתמש בפורמט היומן של LevelDB.

קובצי מטא-נתונים

פעולת ייצוא יוצרת קובץ מטא-נתונים לכל אוסף שציינתם. בדרך כלל, קובצי המטא-נתונים נקראים ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

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

protoc --decode_raw < export0.export_metadata