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

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

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

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

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

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

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. החשבון שדרכו מתבצעת ההרשאה מוצג ליד התווית Import/Export jobs run as.

לסוכן השירות צריכה להיות הרשאת Storage Admin לדלי Cloud Storage שבו ישתמשו לייצוא או לייבוא.

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

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

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

  התחלה Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

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

ייבוא נתונים

אחרי שקבצי הייצוא יהיו ב-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.

• ייבוא למסד נתונים במהדורת Standard של Firestore מייצוא עם סוגי BSON נכשל כי אין תמיכה בסוגי BSON במהדורת Standard של Firestore.

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

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

פעולות הייצוא והייבוא מחילות את התווית 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