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

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

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

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

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

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

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

• אפשר לייבא נתונים שיוצאו ממסד נתונים אחד במצב 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

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

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

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

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

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

3. מקצים לחשבון המשתמש תפקיד IAM שמעניק את ההרשאה datastore.databases.export אם מייצאים נתונים, או את ההרשאה datastore.databases.import אם מייבאים נתונים. לדוגמה, התפקיד Datastore Import Export Admin נותן את שתי ההרשאות.

4. אם הקטגוריה של 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

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

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

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

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

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

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

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

סוכן השירות של 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.

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

   כניסה לדף Databases

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

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

4. בודקים את החשבון המורשה שמופיע לצד התווית 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

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

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

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

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

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

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

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"

$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

{
  "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 firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

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

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

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"

$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

{
  "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

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

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

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

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

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"

$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

{
  "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

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

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

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

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

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

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

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

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

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"

$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

{
  "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 שבהם חותמת הזמן היא חותמת זמן של דקה שלמה בשבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, פעולת הייצוא נכשלת.

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

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

• מפעילים את PITR במסד הנתונים. אם PITR מושבת, הייצוא בחותמת זמן של תמונת מצב נכשל, גם אם חותמות הזמן הן בשעה האחרונה אחרי earliestVersionTime. פעולת הייצוא מחזירה את השגיאה Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp.
• ציינו את חותמת הזמן בפורמט RFC 3339. לדוגמה, 2023-05-26T10:20:00.00Z.
• חשוב לוודא שחותמת הזמן שציינתם היא חותמת זמן של דקה שלמה בשבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, נוצרת שגיאה.
• לא תחויבו על ייצוא PITR שנכשל.

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

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

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

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

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

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

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

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

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

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

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

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

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"
      }
    }
  ]
}

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

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

$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"
      }
    }
  ]
}

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

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

gcloud datastore operations describe operation-name

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

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

$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

{
  "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 בפעולות שמתבצעות.

ביטול פעולה

gcloud datastore operations cancel operation-name

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

מחיקת פעולה

gcloud datastore operations delete operation-name

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

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

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

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

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

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

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

אם השתמשתם בעבר במסוף Datastore 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.

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

   כניסה לדף Databases

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

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

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

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

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

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

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

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

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

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

   כניסה לדף Databases

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

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

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

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

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

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

5. שימו לב לשם של חשבון המשתמש של סוכן השירות של מצב Datastore בפרויקט. שם סוכן השירות מופיע מתחת לתווית Service agent to give access to.

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

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

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

7. לוחצים על Migrate to Firestore Service Agent. אם עדיין יש קטגוריות עם בדיקות הרשאה שנכשלו, צריך לאשר את ההעברה בלחיצה על Migrate.

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

לראות את סטטוס ההעברה

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

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

   כניסה לדף Databases

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

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

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

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

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

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

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

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

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

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

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