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

אתה יכול להשתמש בשירות הייצוא והיבוא המנוהל של Cloud Firestore כדי להתאושש ממחיקה בשוגג של נתונים ולייצא נתונים לעיבוד לא מקוון. אתה יכול לייצא את כל המסמכים או רק אוספים ספציפיים. באופן דומה, אתה יכול לייבא את כל הנתונים מיצוא או רק מאוספים ספציפיים. ניתן לייבא נתונים המיוצאים ממסד נתונים אחד של 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 . אינך יכול להשתמש בדלי Requester Pays עבור פעולות ייצוא וייבוא.

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

   • תפקידי Cloud Firestore: Owner , Cloud Datastore Owner או Cloud Datastore Import Export Admin

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

לחלופין, תוכל להקצות תפקיד זה באמצעות מסוף GCP .

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

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

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

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

הגדר gcloud עבור הפרויקט שלך

אתה יכול ליזום פעולות ייבוא ​​וייצוא דרך Google Cloud Platform Console או כלי שורת הפקודה gcloud . כדי להשתמש gcloud , הגדר את כלי שורת הפקודה והתחבר לפרויקט שלך באחת מהדרכים הבאות:

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

  הפעל את Cloud Shell

  ודא gcloud מוגדר עבור הפרויקט הנכון:

  gcloud config set project [PROJECT_ID]
  

• התקן ואתחול את Google Cloud SDK.

ייצוא נתונים

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

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

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

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

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

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

ייבוא ​​נתונים

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

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

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

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

• פעולות ייבוא ​​לא מפעילות פונקציות ענן. מאזיני Snapshot אכן מקבלים עדכונים הקשורים לפעולות הייבוא.

• שם הקובץ .overall_export_metadata חייב להתאים לשם של תיקיית האב שלו:

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

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

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

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],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

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

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

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

projects/my-project/databases/(default)/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 על פעולות החיוב. בדף דוחות חיוב בענן , תוכל להשתמש בתווית זו כדי להציג עלויות הקשורות לפעולות ייבוא ​​וייצוא:

ייצא ל-BigQuery

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

מגבלת עמודות 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

העברת סוכני שירות

Cloud Firestore משתמש בסוכן שירות Cloud Firestore כדי לאשר פעולות ייבוא ​​וייצוא במקום להשתמש בחשבון השירות של App Engine. סוכן השירות וחשבון השירות משתמשים במוסכמות השמות הבאות:

סוכן שירות Cloud Firestore

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

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

חשבון שירות App Engine

PROJECT_ID @appspot.gserviceaccount.com

סוכן השירות Cloud Firestore עדיף מכיוון שהוא ספציפי ל-Cloud Firestore. חשבון השירות של App Engine משותף ליותר משירות אחד.

הצג חשבון הרשאה

אתה יכול לראות באיזה חשבון פעולות הייבוא ​​והייצוא שלך משתמשות כדי לאשר בקשות מדף הייבוא/ייצוא ב-Google Cloud Platform Console. אתה יכול גם לראות אם מסד הנתונים שלך כבר משתמש בסוכן השירות Cloud Firestore.

1. ב-Google Cloud Platform Console, עבור לדף מסדי נתונים .

   עבור אל מסדי נתונים

2. בחר את מסד הנתונים הנדרש מרשימת מסדי הנתונים.

3. בתפריט הניווט, לחץ על ייבוא/ייצוא .

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

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

• העבר פרויקט על ידי בדיקה ועדכון של הרשאות דלי Cloud Storage (מומלץ) .
• הוסף אילוץ מדיניות כלל-ארגוני המשפיע על כל הפרויקטים בתוך הארגון.

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

העבר על ידי בדיקה ועדכון של הרשאות דלי של Cloud Storage

תהליך ההגירה כולל שני שלבים:

1. עדכן הרשאות דלי של Cloud Storage. עיין בסעיף הבא לפרטים.
2. אשר את ההעברה לסוכן השירות Cloud Firestore.

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

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

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

עדכן את ההרשאות עבור דליים של Cloud Storage מפרויקטים אחרים כדי לתת גישה לשירות service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com סוכן השירות. הענק לסוכן השירות את תפקיד Firestore Service Agent .

תפקיד Firestore Service Agent מעניק הרשאות קריאה וכתיבה עבור דלי של Cloud Storage. אם אתה צריך להעניק הרשאות קריאה או כתיבה בלבד, השתמש בתפקיד מותאם אישית .

תהליך ההעברה המתואר בסעיף הבא עוזר לך לזהות דליים של Cloud Storage שעשויים לדרוש עדכוני הרשאות.

העבר פרויקט ל-Firestore Service Agent

השלם את השלבים הבאים כדי לעבור מחשבון שירות App Engine לסוכן השירות של Cloud Firestore. לאחר השלמת, לא ניתן לבטל את ההעברה.

1. ב-Google Cloud Platform Console, עבור לדף מסדי נתונים .

   עבור אל מסדי נתונים

2. בחר את מסד הנתונים הנדרש מרשימת מסדי הנתונים.

3. בתפריט הניווט, לחץ על ייבוא/ייצוא .

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

   לחץ על בדוק סטטוס דלי .

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

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

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

6. עבור כל דלי ברשימה שבו תשתמש לפעולות ייבוא ​​או ייצוא עתידיות, בצע את השלבים הבאים:

   1. בשורת הטבלה של דלי זה, לחץ על תקן . זה פותח את דף ההרשאות של הדלי הזה בכרטיסייה חדשה.

   2. לחץ על הוסף .
   3. בשדה עקרונות חדשים , הזן את השם של סוכן השירות שלך ב-Cloud Firestore.
   4. בשדה בחר תפקיד , בחר שירות סוכני > Firestore Service Agent .
   5. לחץ על שמור .
   6. חזור לכרטיסייה עם דף הייבוא/ייצוא של Cloud Firestore.
   7. חזור על שלבים אלה עבור דליים אחרים ברשימה. הקפד לצפות בכל דפי הרשימה.

7. לחץ על העבר ל-Firestore Service Agent . אם עדיין יש לך דליים עם בדיקות הרשאות כושלות, עליך לאשר את ההעברה על ידי לחיצה על העבר .

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

הצג את סטטוס ההגירה

כדי לאמת את סטטוס ההגירה של הפרויקט שלך:

1. ב-Google Cloud Platform Console, עבור לדף מסדי נתונים .

   עבור אל מסדי נתונים

2. בחר את מסד הנתונים הנדרש מרשימת מסדי הנתונים.

3. בתפריט הניווט, לחץ על ייבוא/ייצוא .

4. חפש את המנהל ליד משימות הייבוא/ייצוא המופעלות כתווית .

   אם המנהל הוא service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com , הפרויקט שלך כבר הועבר לסוכן השירות של Cloud Firestore. לא ניתן לבטל את ההגירה.

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

הוסף אילוץ מדיניות כלל הארגון

• הגדר את האילוץ הבא במדיניות הארגון שלך:

  דרוש Firestore Service Agent עבור ייבוא/ייצוא ( firestore.requireP4SAforImportExport ).

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

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

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