Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

בדף הזה מוסבר איך לייצא ולייבא ישויות של Firestore במצב Datastore באמצעות שירות הייצוא והייבוא המנוהל. שירות הייצוא והייבוא המנוהל זמין דרך מסוף Google Cloud,‏ Google Cloud CLI ו-Datastore Admin API‏ (REST,‏ RPC). Google Cloud

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

שירות הייצוא משתמש בקריאות עקביות הדרגתיות. אי אפשר להניח שהייצוא מתבצע בנקודת זמן אחת. יכול להיות שהייצוא יכלול ישויות שנכתבו אחרי שהייצוא התחיל, ולא יכלול ישויות שנכתבו לפני שהייצוא התחיל.
ייצוא לא מכיל אינדקסים. כשמייבאים נתונים, המערכת בונה מחדש באופן אוטומטי את האינדקסים הנדרשים באמצעות הגדרות האינדקס הנוכחיות של מסד הנתונים. הגדרות האינדקס של ערכי מאפיינים לכל ישות מיוצאות ונשמרות במהלך הייבוא.
בייבוא לא מוקצים מזהים חדשים לישויות. בייבוא נעשה שימוש במזהים שהיו קיימים בזמן הייצוא, והוא מחליף כל ישות קיימת עם אותו מזהה. במהלך הייבוא, המזהים מוזמנים למשך הזמן שבו מתבצע הייבוא של הישויות. התכונה הזו מונעת התנגשויות בין מזהים של ישויות חדשות אם כתיבה מופעלת בזמן שהייבוא פועל.
אם יש ישות במסד הנתונים שלכם שלא מושפעת מייבוא, היא תישאר במסד הנתונים אחרי הייבוא.
אפשר לייבא נתונים שמיוצאים ממסד נתונים במצב Datastore למסד נתונים אחר במצב Datastore, גם אם הוא נמצא בפרויקט אחר.
שירות הייצוא והייבוא המנוהל מגביל את מספר הייצוא והייבוא בו-זמנית ל-50, ומאפשר מקסימום 20 בקשות ייצוא וייבוא לדקה לכל פרויקט. לכל בקשה, השירות מגביל את מספר השילובים של מסנני ישויות ל-100.
הפלט של ייצוא מנוהל הוא בפורמט היומן של LevelDB.
כדי לייבא רק קבוצת משנה של ישויות או לייבא נתונים ל-BigQuery, צריך להגדיר מסנן ישויות בייצוא.
שם הקובץ .overall_export_metadata צריך להיות זהה לשם תיקיית האב שלו:

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

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

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

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

מפעילים את החיוב בפרויקט Google Cloud . אפשר להשתמש בתכונות הייצוא והייבוא רק בפרויקטים שמופעל בהם חיוב. Google Cloud
יוצרים קטגוריה של Cloud Storage באותו מיקום של מסד הנתונים של Firestore במצב Datastore. אי אפשר להשתמש בקטגוריה שבה מופעלת התכונה 'מגיש הבקשה משלם' או בקטגוריה מהירה לצורך פעולות ייצוא וייבוא.
אם אתם מייצאים נתונים, צריך להקצות תפקיד IAM לחשבון המשתמש שלכם שמעניק את ההרשאה datastore.databases.export. אם אתם מייבאים נתונים, צריך להקצות תפקיד שמעניק את ההרשאה datastore.databases.import. לדוגמה, התפקיד Datastore Import Export Admin נותן את שתי ההרשאות.
אם הקטגוריה של Cloud Storage נמצאת בפרויקט אחר, צריך לתת לסוכן השירות של Firestore גישה לקטגוריה.

הגדרה של `gcloud` לפרויקט

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

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

מפעילים את Cloud Shell

מגדירים את ה-CLI של gcloud לשימוש בפרויקט הנוכחי:
```
gcloud config set project project-id
```
מתקינים ומפעילים את Google Cloud CLI.

הרשאות

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

הרשאות בחשבון משתמש

לחשבון המשתמש או לחשבון השירות שמפעילים את הפעולה צריכות להיות הרשאות ה-IAM‏ datastore.databases.export ו-datastore.databases.import. אם אתם הבעלים של הפרויקט, לחשבון שלכם יש את ההרשאות הנדרשות. אחרת, תפקידי ה-IAM הבאים מעניקים את ההרשאות הנדרשות:

הבעלים של Datastore
Datastore Import Export Admin

אפשר גם להקצות את ההרשאות האלה באמצעות תפקיד בהתאמה אישית.

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

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

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

סוכן שירות של Firestore: service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

מידע נוסף על סוכני שירות זמין במאמר סוכני שירות.

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

אם אתם משתמשים ב-VPC Service Controls, אתם צריכים להשתמש בסוכן שירות ספציפי לשירות Firestore כדי להגן באופן מלא על פעולות ייבוא וייצוא. ‫VPC Service Controls לא תואם לחשבון השירות של App Engine.

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

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

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

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

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

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

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

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

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

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

מעבר אל Databases
בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על ייבוא/ייצוא.
החשבון המורשה מוצג ליד התווית Import/Export jobs run as.

פעולות ייצוא

לפעולות ייצוא שכוללות קטגוריה בפרויקט אחר, צריך לשנות את ההרשאות של הקטגוריה כדי להקצות אחד מהתפקידים הבאים בניהול זהויות והרשאות גישה (IAM) לסוכן השירות במצב Datastore של הפרויקט שמכיל את מסד הנתונים במצב Datastore:

ניהול נפח האחסון
בעלים (תפקיד בסיסי)

אפשר גם ליצור תפקיד IAM בהתאמה אישית עם הרשאות שונות במקצת מאלה שנכללות בתפקידים שצוינו קודם:

storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.list

פעולות ייבוא

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

ניהול נפח האחסון
גם Storage Object Viewer וגם Storage Legacy Bucket Reader

אפשר גם ליצור תפקיד ב-IAM בהתאמה אישית עם ההרשאות הבאות:

storage.buckets.get
storage.objects.get

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

בקטע הזה מוסבר איך מתחילים פעולת ייצוא או ייבוא מנוהלת.

ייצוא של כל הישויות

המסוף

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

מעבר אל Databases
בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.

בתפריט הניווט, לוחצים על ייבוא/ייצוא.
לוחצים על ייצוא.
מגדירים את השדה Namespace [מרחב שמות] ל-All Namespaces ואת השדה Kind [סוג] ל-All Kinds.
בקטע יעד, מזינים את השם של קטגוריית Cloud Storage.
לוחצים על ייצוא.

המסוף חוזר לדף Import/Export. התראה תדווח על הצלחה או על כשלון של בקשת הייצוא המנוהל.

gcloud

כדי לייצא את כל הישויות במסד הנתונים, משתמשים בפקודה gcloud firestore export.

 gcloud firestore export gs://bucket-name --async --database=DATABASE

כאשר bucket-name הוא השם של הקטגוריה שלכם ב-Cloud Storage וקידומת אופציונלית, לדוגמה, bucket-name/datastore-exports/export-name. אי אפשר להשתמש מחדש באותו קידומת לפעולת ייצוא אחרת. אם לא תציינו קידומת לקובץ, שירות הייצוא המנוהל ייצור קידומת על סמך השעה הנוכחית.

כדי למנוע מ-gcloud להמתין לסיום הפעולה, משתמשים בדגל --async. אם לא מציינים את האפשרות --async, אפשר להקליד Ctrl+c כדי להפסיק את ההמתנה לפעולה. הפעולה לא תבוטל.

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

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט
‫bucket-name: שם הקטגוריה של Cloud Storage

ה-method של ה-HTTP וכתובת ה-URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

תוכן בקשת JSON:

{
  "outputUrlPrefix": "gs://bucket-name",
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}

התשובה היא פעולה ממושכת, שאפשר לבדוק אם היא הושלמה.

ייצוא של סוגים או מרחבי שמות ספציפיים

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

המסוף

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

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

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

מעבר אל Databases
בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על ייבוא/ייצוא.
לוחצים על ייצוא.
מגדירים את השדה Namespace [מרחב שמות] לערך All Namespaces או לשם של אחד ממרחבי השמות.
מגדירים את השדה Kind [סוג] ל-All Kinds או לשם של סוג.
בקטע יעד, מזינים את השם של הקטגוריה ב-Cloud Storage.
לוחצים על ייצוא.

המסוף חוזר לדף Import/Export. התראה תדווח על הצלחה או על כשלון של בקשת הייצוא המנוהל.

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

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

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט
‫bucket-name: שם הקטגוריה של Cloud Storage
‫kind: סוג הישות
‫namespace: המזהה של מרחב השמות (משתמשים ב-"" למזהה ברירת המחדל של מרחב השמות)

ה-method של ה-HTTP וכתובת ה-URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

תוכן בקשת JSON:

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

‎PowerShell (Windows)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}

התשובה היא פעולה ממושכת, שאפשר לבדוק אם היא הושלמה.

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

פעולת ייצוא יוצרת קובץ מטא-נתונים לכל זוג של מרחב שמות וסוג שצוין. בדרך כלל קובצי מטא-נתונים נקראים NAMESPACE_NAME_KIND_NAME.export_metadata. עם זאת, אם מרחב שמות או סוג יוצרים שם אובייקט לא תקין ב-Cloud Storage, שם הקובץ יהיה export[NUM].export_metadata.

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

protoc --decode_raw < export0.export_metadata

ייבוא של כל הישויות

המסוף

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

מעבר אל Databases
בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על ייבוא/ייצוא.
לוחצים על Import.
בשדה File, לוחצים על עיון ובוחרים קובץ .overall_export_metadata.

מוודאים שקובץ .overall_export_metadata לא הועבר מהמיקום שמוגדר כברירת מחדל.
מגדירים את השדה Namespace [מרחב שמות] ל-All Namespaces ואת השדה Kind [סוג] ל-All Kinds.
לוחצים על Import.

המסוף חוזר לדף Import/Export. התראה תדווח על הצלחה או כישלון של בקשת הייבוא המנוהל.

gcloud

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

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

כאשר bucket-name/file-path/file-name הוא הנתיב לקובץ overall_export_metadata בקטגוריה של Cloud Storage.

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

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט
‫bucket-name: שם הקטגוריה של Cloud Storage
‫object-name: שם האובייקט שלכם ב-Cloud Storage (לדוגמה: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

ה-method של ה-HTTP וכתובת ה-URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

תוכן בקשת JSON:

{
  "inputUrl": "gs://bucket-name/object-name",
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

‎PowerShell (Windows)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}

התשובה היא פעולה ממושכת, שאפשר לבדוק אם היא הושלמה.

איתור הקובץ `overall_export_metadata`

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

פתיחת Cloud Storage Browser

אפשר גם לפרט ולתאר פעולות שהושלמו. בשדה outputURL מוצג השם של הקובץ overall_export_metadata:

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

ייבוא של סוגים או מרחבי שמות ספציפיים

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

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

המסוף

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

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

מעבר אל Databases
בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על ייבוא/ייצוא.
לוחצים על Import.
בשדה File, לוחצים על עיון ובוחרים קובץ .overall_export_metadata.

חשוב לוודא שמייבאים את הקובץ .overall_export_metadata ולא את הקובץ .export_metadata.
מגדירים את השדה Namespace [מרחב שמות] בתור All Namespaces או בתור מרחב שמות ספציפי.
מגדירים את השדה Kind [סוג] לערך All Kinds או לסוג ספציפי.
לוחצים על Import.

המסוף חוזר לדף Import/Export. התראה תדווח על הצלחה או כישלון של בקשת הייבוא המנוהל.

gcloud

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

כאשר bucket-name/file-path/file-name הוא הנתיב לקובץ overall_export_metadata בקטגוריה של Cloud Storage.

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

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט
‫bucket-name: שם הקטגוריה של Cloud Storage
‫object-name: שם האובייקט שלכם ב-Cloud Storage (לדוגמה: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata
‫kind: סוג הישות
‫namespace: המזהה של מרחב השמות (משתמשים ב-"" למזהה ברירת המחדל של מרחב השמות)

ה-method של ה-HTTP וכתובת ה-URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

תוכן בקשת JSON:

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:import"

‎PowerShell (Windows)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:import" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}

התשובה היא פעולה ממושכת, שאפשר לבדוק אם היא הושלמה.

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

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

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

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

מציינים את חותמת הזמן בפורמט RFC 3339. לדוגמה, 2023-05-26T10:20:00.00Z.
חשוב לוודא שחותמת הזמן שציינתם היא חותמת זמן של דקה שלמה במהלך שבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, נוצרת שגיאה.
לא נחייב אתכם על ייצוא PITR שנכשל.

המסוף

נכנסים לדף Databases במסוף Google Cloud .
מעבר אל Databases
בוחרים מסד נתונים מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על ייבוא/ייצוא.
לוחצים על ייצוא.
בחירת מרחב שמות לייצוא
בוחרים את הסוגים לייצוא.
בקטע Choose the state of your database to export (בחירת מצב מסד הנתונים לייצוא), בוחרים באפשרות Export from an earlier point in time (ייצוא מנקודת זמן מוקדמת יותר).

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

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

gcloud

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

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

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.

ייבוא טרנספורמציות

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

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

ניהול פעולות ממושכות

פעולות ייבוא וייצוא מנוהלות הן פעולות ממושכות. הקריאות האלה לשיטות יכולות להימשך זמן רב.

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

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

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

כשמציינים שם של פעולה לפקודות gcloud, אפשר להשמיט את הקידומת.

הצגת רשימה של כל הפעולות לטווח ארוך

אפשר לראות את הפעולות שמתבצעות ואת הפעולות שהסתיימו לאחרונה בדרכים הבאות. הפעולות מופיעות למשך כמה ימים אחרי שהן מסתיימות:

המסוף

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

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

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

gcloud

כדי לראות את רשימת הפעולות הממושכות, משתמשים בפקודה gcloud datastore operations list.

gcloud datastore operations list

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

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט

ה-method של ה-HTTP וכתובת ה-URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

‎PowerShell (Windows)

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

מידע על התשובה מופיע בהמשך.

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

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

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

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

המסוף

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

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

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

gcloud

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

gcloud datastore operations describe operation-name

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט
‫operation-name: שם הפעולה

ה-method של ה-HTTP וכתובת ה-URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name"

‎PowerShell (Windows)

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

חישוב משוער של זמן ההשלמה

במהלך הפעולה, אפשר לראות את הערך של השדה state כדי לדעת מה הסטטוס הכולל של הפעולה.

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

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

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

לדוגמה, הסטטוס של התקדמות פעולת ייצוא:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

כשפעולה מסתיימת, תיאור הפעולה מכיל את הערך "done": true. התוצאה של הפעולה מופיעה בערך של השדה state. אם השדה done לא מוגדר בתגובה, הערך שלו הוא false. אל תסתמכו על קיומו של הערך done בפעולות שנמצאות בתהליך.

ביטול פעולה

המסוף

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

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

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

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

gcloud

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

gcloud datastore operations cancel operation-name

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

מחיקת פעולה

gcloud

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

gcloud datastore operations delete operation-name

חיוב ותמחור של ייבוא וייצוא מנוהלים

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

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

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

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

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

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

הבדלים מגיבויים של Datastore Admin

אם השתמשתם בעבר במסוף Admin של Datastore לגיבויים, חשוב לשים לב להבדלים הבאים:

ייצוא שנוצר על ידי ייצוא מנוהל לא מופיע במסוף Admin של מאגר הנתונים. ייצוא וייבוא מנוהלים הם שירות חדש שלא משתף נתונים עם התכונה של גיבוי ושחזור ב-App Engine, שמנוהלת דרך Google Cloud המסוף.
שירות הייצוא והייבוא המנוהל לא תומך באותם מטא-נתונים כמו הגיבוי של Datastore Admin, והוא לא שומר את סטטוס ההתקדמות במסד הנתונים. מידע על בדיקת ההתקדמות של פעולות ייצוא וייבוא זמין במאמר בנושא ניהול פעולות ממושכות
אי אפשר לראות את יומני השירות של פעולות ייצוא וייבוא מנוהלות.
שירות הייבוא המנוהל תואם לאחור לקובצי גיבוי של Datastore Admin. אפשר לייבא קובץ גיבוי של Datastore Admin באמצעות שירות הייבוא המנוהל, אבל אי אפשר לייבא את הפלט של ייצוא מנוהל באמצעות מסוף Datastore Admin.

ייבוא ל-BigQuery

כדי לייבא נתונים מייצוא מנוהל ל-BigQuery, אפשר לעיין במאמר בנושא טעינת נתונים משירות הייצוא של Datastore.

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

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

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

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

העברה של סוכן שירות

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

סוכן שירות של Firestore: service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

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

חשבון שירות של App Engine: PROJECT_ID@appspot.gserviceaccount.com

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

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

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

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

מעבר אל Databases
בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.
בתפריט הניווט, לוחצים על ייבוא/ייצוא.
החשבון המורשה מוצג ליד התווית Import/Export jobs run as.

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

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

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

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

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

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

הרשאות של סוכן שירות לקטגוריה

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

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

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

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

לוחצים על Check Bucket Status (בדיקת סטטוס מאגר).

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

הרשימה הזו כוללת מאגרי מידע שהיו בשימוש לאחרונה בפעולות ייבוא וייצוא, אבל כרגע לא מוקצות להם הרשאות קריאה וכתיבה לסוכן השירות של מצב Datastore.
רושמים את שם חשבון המשתמש של סוכן השירות של פרויקט במצב Datastore. שם סוכן השירות מופיע מתחת לתווית Service agent to give access to.
לכל קטגוריה ברשימה שבה תשתמשו בעתיד לפעולות ייבוא או ייצוא, צריך לבצע את השלבים הבאים:
1. בשורה של הדלי בטבלה, לוחצים על Fix (תיקון). ייפתח דף ההרשאות של מאגר הנתונים בכרטיסייה חדשה.
2. לוחצים על הוספה.
3. בשדה New principals, מזינים את השם של סוכן השירות של Firestore.
4. בשדה Select a role בוחרים באפשרות Service Agents > Firestore Service Agent.
5. לוחצים על Save.
6. חוזרים לכרטיסייה עם הדף 'ייבוא/ייצוא' במצב Datastore.
7. חוזרים על השלבים האלה לגבי דליים אחרים ברשימה. חשוב לעיין בכל הדפים של הרשימה.
לוחצים על Migrate to Firestore Service Agent (מעבר לסוכן שירות של Firestore). אם עדיין יש לכם מאגרי מידע שבהם בדיקות ההרשאות נכשלו, אתם צריכים לאשר את ההעברה על ידי לחיצה על העברה.

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

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

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

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

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

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

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

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

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

Require Firestore Service Agent for import/export (firestore.requireP4SAforImportExport).

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

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

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

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

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

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

הרשאות

הרשאות בחשבון משתמש

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

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

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

פעולות ייצוא

פעולות ייבוא

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

ייצוא של כל הישויות

המסוף

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

ייצוא של סוגים או מרחבי שמות ספציפיים

המסוף

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

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

ייבוא של כל הישויות

המסוף

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

איתור הקובץ overall_export_metadata

ייבוא של סוגים או מרחבי שמות ספציפיים

המסוף

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

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

המסוף

gcloud

ייבוא טרנספורמציות

ניהול פעולות ממושכות

הצגת רשימה של כל הפעולות לטווח ארוך

המסוף

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

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

המסוף

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

חישוב משוער של זמן ההשלמה

ביטול פעולה

המסוף

gcloud

מחיקת פעולה

gcloud

חיוב ותמחור של ייבוא וייצוא מנוהלים

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

הבדלים מגיבויים של Datastore Admin

ייבוא ל-BigQuery

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

העברה של סוכן שירות

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

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

הרשאות של סוכן שירות לקטגוריה

העברת פרויקט לסוכן השירות של Firestore

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

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

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

הגדרה של `gcloud` לפרויקט

איתור הקובץ `overall_export_metadata`