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

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

ייצוא נתונים

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

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

Google Cloud Console

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

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

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

  4. לוחצים על ייצוא.

  5. לוחצים על האפשרות Export entire database (ייצוא כל מסד הנתונים).

  6. מתחת לChoose Destination, מזינים את השם של קטגוריית Cloud Storage או משתמשים בלחצן Browse כדי לבחור קטגוריה.

  7. לוחצים על ייצוא.

המסוף חוזר לדף Import/Export. אם הפעולה מתחילה בהצלחה, תיכנס רשומה לדף של הייבוא והייצוא האחרונים. אם הפעולה נכשלת, תוצג בדף הודעת שגיאה.

gcloud

משתמשים בפקודה firestore export כדי לייצא את כל המסמכים במסד הנתונים, מחליפים את [BUCKET_NAME] בשם הקטגוריה Cloud Storage. מוסיפים את הדגל --async כדי למנוע מהכלי gcloud להמתין לסיום הפעולה.

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

מחליפים את מה שכתוב בשדות הבאים:

  • BUCKET_NAME: לארגן את הייצוא על ידי הוספת תחילית לקובץ אחרי שם הקטגוריה, לדוגמה BUCKET_NAME/my-exports-folder/export-name. אם לא תספקו קידומת לקובץ, שירות הייצוא המנוהל ייצור קידומת על סמך חותמת הזמן הנוכחית.

  • DATABASE: שם מסד הנתונים שממנו רוצים לייצא את המסמכים. למסד הנתונים שמוגדר כברירת מחדל, משתמשים ב---database='(default)'.

אחרי שמתחילים פעולת ייצוא, סגירת המסוף לא מבטלת את הפעולה. אפשר לעיין במאמר ביטול פעולה.

ייצוא קולקציות ספציפיות

Google Cloud Console

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

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

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

  4. לוחצים על ייצוא.

  5. לוחצים על האפשרות ייצוא קבוצת אוספים אחת או יותר. בוחרים קבוצת אוספים אחת או יותר בתפריט הנפתח.

  6. מתחת לChoose Destination, מזינים את השם של קטגוריית Cloud Storage או משתמשים בלחצן Browse כדי לבחור קטגוריה.

  7. לוחצים על ייצוא.

המסוף חוזר לדף Import/Export. אם הפעולה מתחילה בהצלחה, תיכנס רשומה לדף של הייבוא והייצוא האחרונים. אם הפעולה נכשלת, תוצג בדף הודעת שגיאה.

gcloud

כדי לייצא קבוצות ספציפיות של אוספים, משתמשים בדגל --collection-ids. הפעולה מייצאת רק את קבוצות הקולקציות עם מזהי הקולקציות שצוינו. קבוצת האוספים כוללת את כל האוספים ואוספי המשנה (בכל נתיב) עם מזהה האוסף שצוין.

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

לדוגמה, אפשר לתכנן אוסף restaurants במסד הנתונים foo כך שיכלול כמה אוספים משניים, כמו ratings,‏ reviews או outlets. כדי לייצא את האוספים הספציפיים restaurants ו-reviews, הפקודה נראית כך:

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

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

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

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

  1. מייצאים את מסד הנתונים, מציינים את הפרמטר snapshot-time לחותמת הזמן הרצויה לשחזור.

    gcloud

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

    gcloud firestore export gs://[BUCKET_NAME_PATH] \
        --snapshot-time=[PITR_TIMESTAMP] \
        --collection-ids=[COLLECTION_IDS] \
        --namespace-ids=[NAMESPACE_IDS]
    

    איפה,

    • PITR_TIMESTAMP – חותמת זמן של PITR ברמת פירוט של דקה, לדוגמה, 2023-05-26T10:20:00.00Z.

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

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

ייבוא נתונים

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

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

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

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

  • פעולות ייבוא לא מפעילות את Cloud Functions. מאזינים ל-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.

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

Google Cloud Console

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

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

  3. בתפריט הניווט, לוחצים על Import/Export.

  4. לוחצים על ייבוא.

  5. בשדה Filename, מזינים את שם הקובץ של קובץ .overall_export_metadata מפעולה של ייצוא שהושלם. אפשר להשתמש בלחצן עיון כדי לבחור את הקובץ.

  6. לוחצים על ייבוא.

המסוף חוזר לדף Import/Export. אם הפעולה מתחילה בהצלחה, תיכנס רשומה לדף של הייבוא והייצוא האחרונים. אם הפעולה נכשלת, תוצג בדף הודעת שגיאה.

gcloud

משתמשים בפקודה firestore import כדי לייבא מסמכים מפעולה קודמת של ייצוא.

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

מחליפים את מה שכתוב בשדות הבאים:

  • BUCKET_NAME/EXPORT_PREFIX: המיקום של קובצי הייצוא.

  • DATABASE: שם מסד הנתונים. למסד הנתונים שמוגדר כברירת מחדל, משתמשים ב---database='(default)'.

לדוגמה:

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

אפשר לאמת את המיקום של קובצי הייצוא בדפדפן Cloud Storage במסוף Google Cloud:

פתיחת הדפדפן Cloud Storage

אחרי שמתחילים פעולת ייבוא, סגירת המסוף לא מבטלת את הפעולה. אפשר לעיין במאמר ביטול פעולה.

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

Google Cloud Console

אי אפשר לבחור אוספים ספציפיים במסוף. במקום זאת, אתם צריכים להשתמש ב-gcloud.

gcloud

כדי לייבא קבוצות ספציפיות של אוספים מקבוצה של קובצי ייצוא, משתמשים בדגל --collection-ids. הפעולה מייבאת רק את קבוצות האוספים עם מזהי האוספים שצוינו. קבוצת האוספים כוללת את כל האוספים ואוספי המשנה (בכל נתיב) עם מזהה האוסף שצוין. מציינים את שם מסד הנתונים באמצעות הדגל --database. למסד הנתונים שמוגדר כברירת מחדל, משתמשים ב---database='(default)'.

רק ייצוא של קבוצות אוספים ספציפיות תומך בייבוא של קבוצות אוספים ספציפיות. אי אפשר לייבא אוספים ספציפיים מייצוא של כל המסמכים.

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

ייבוא של קובץ PITR שיוצא

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

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

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

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

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

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

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

Google Cloud Console

אפשר לראות רשימה של פעולות ייצוא וייבוא שבוצעו לאחרונה בדף Import/Export במסוף Google Cloud.

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

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

  3. בתפריט הניווט, לוחצים על Import/Export.

gcloud

משתמשים בפקודה operations list כדי לראות את כל פעולות הייצוא והייבוא שפועלות ועברו לאחרונה:

gcloud firestore operations list

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

Google Cloud Console

אפשר לראות את הסטטוס של פעולת ייצוא או ייבוא שבוצעה לאחרונה בדף Import/Export במסוף Google Cloud.

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

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

  3. בתפריט הניווט, לוחצים על Import/Export.

gcloud

משתמשים בפקודה operations describe כדי להציג את הסטטוס של פעולת ייצוא או ייבוא.

gcloud firestore operations describe [OPERATION_NAME]

אומדן של זמן השלמה

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

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

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

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

ביטול פעולה

Google Cloud Console

אפשר לבטל פעולת ייצוא או ייבוא קיימת בדף Import/Export במסוף Google Cloud.

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

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

  3. בתפריט הניווט, לוחצים על Import/Export.

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

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

gcloud

משתמשים בפקודה operations cancel כדי לעצור פעולה מתמשכת:

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, תוכלו להשתמש בתווית הזו כדי להציג עלויות שקשורות לפעולות ייבוא וייצוא:

ניגשים לתווית goog-firestoremanaged מתפריט המסננים.

ייצוא אל 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 משותף למספר שירותים.

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

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

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

  2. בוחרים את מסד הנתונים הנדרש מרשימת מסדי הנתונים.
  3. בתפריט הניווט, לוחצים על Import/Export.

  4. בודקים את חשבון ההרשאה לצד התווית Import/Export jobs run as.

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

מומלץ להשתמש בשיטה הראשונה כי היא מגבילה את ההשפעה לפרויקט 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

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

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

  2. בוחרים את מסד הנתונים הנדרש מרשימת מסדי הנתונים.
  3. בתפריט הניווט, לוחצים על Import/Export.

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

    לוחצים על Check Bucket Status.

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

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

  5. שימו לב לשם חשבון המשתמש של סוכן השירות Cloud Firestore של הפרויקט. שם סוכן השירות מופיע מתחת לתווית Service agent to give access to.
  6. לכל קטגוריה ברשימה שבה תשתמשו בעתיד לפעולות ייבוא או ייצוא, מבצעים את הפעולות הבאות:

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

    2. לוחצים על הוספה.
    3. בשדה New principals, מזינים את השם של סוכן השירות Cloud Firestore.
    4. בשדה Select a role בוחרים באפשרות Service Agents > Firestore Service Agent.
    5. לוחצים על שמירה.
    6. חוזרים לכרטיסייה שבה מוצג הדף Cloud Firestore Import/Export (ייבוא/ייצוא).
    7. חוזרים על השלבים האלה לקטגוריות אחרות ברשימה. חשוב להציג את כל הדפים ברשימה.
  7. לוחצים על Migrate to Firestore Service Agent. אם עדיין יש לכם קטגוריות שבהן בדיקות ההרשאות נכשלו, תצטרכו לאשר את ההעברה בלחיצה על Migrate.

    תקבלו התראה כשההעברה תסתיים. אי אפשר לבטל את ההעברה.

הצגת סטטוס ההעברה

כדי לבדוק את סטטוס ההעברה של הפרויקט:

  1. נכנסים לדף Databases במסוף Google Cloud.

    כניסה לדף Databases

  2. בוחרים את מסד הנתונים הנדרש מרשימת מסדי הנתונים.
  3. בתפריט הניווט, לוחצים על Import/Export.

  4. מחפשים את חשבון המשתמש לצד התווית Import/Export jobs run as.

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

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

הוספת אילוץ מדיניות ברמת הארגון

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

    דרישה לסוכן שירות של Firestore לייבוא/ייצוא (firestore.requireP4SAforImportExport).

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

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

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