שימוש בפעולות ארוכות טווח ב-Cloud Storage

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

קבלת התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לניהול פעולות ממושכות ב-Cloud Storage, צריך לבקש מהאדמין להקצות לכם את התפקיד 'אדמין לניהול אחסון' (roles/storage.admin) או את התפקיד 'בעלים של קטגוריה מדור קודם' (roles/storage.legacyBucketOwner) בקטגוריה או בפרויקט שמשמשים לביצוע הפעולה הבסיסית.

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

  • storage.bucketOperations.cancel
  • storage.bucketOperations.get
  • storage.bucketOperations.list
  • ‫storage.buckets.list (ההרשאה הזו נדרשת רק כשמשתמשים במסוף Google Cloud )

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

קבלת פרטים על פעולה ממושכת

המסוף

  1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.

    כניסה לדף Buckets

  2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמשויכת לפעולה הממושכת.

  3. לוחצים על הכרטיסייה פעולות.

שורת הפקודה

כדי לקבל את הפרטים או לבדוק את הסטטוס של פעולה ממושכת, משתמשים בפקודה gcloud storage operations describe:

gcloud storage operations describe projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

מחליפים את:

  • ‫BUCKET_NAME בשם הקטגוריה שמכילה את הפעולה הממושכת. לדוגמה, my-bucket.

  • ‫OPERATION_ID עם המזהה של הפעולה הממושכת, שמוחזר בתגובה של השיטות שקוראים להן. לדוגמה, התגובה הבאה מוחזרת מקריאה ל-gcloud storage restore ומזהה הפעולה הממושכת הוא BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

ממשקי API ל-REST

API ל-JSON

  1. התקנה והפעלה של ה-CLI של gcloud, שמאפשרות ליצור אסימון גישה לכותרת Authorization.

  2. משתמשים ב- cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת operations.get:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID"

    מחליפים את:

    • ‫BUCKET_NAME בשם הקטגוריה שמשויכת לפעולה הממושכת.

    • ‫OPERATION_ID עם המזהה של הפעולה הממושכת, שמוחזר בתשובה של השיטות שאתם מפעילים. לדוגמה, התגובה הבאה מוחזרת מקריאה ל-gcloud storage restore ומזהה הפעולה הממושכת הוא BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

אם הבקשה מצליחה, מוחזר משאב operations:

{
  "kind": "storage#operation",
  "name": "projects/_/buckets/bucket/operations/operation_id",
  "metadata": {
    "@type": OperationMetadataType*,
    metadata OperationMetadata*
  },
  "done": boolean,
  "response": {
    "@type": ResponseResourceType*,
    response ResponseResource*
  }
}

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

המסוף

  1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.

    כניסה לדף Buckets

  2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה.

  3. לוחצים על הכרטיסייה פעולות.

שורת הפקודה

כדי להציג את הפעולות הממושכות בקטגוריה, משתמשים בפקודה gcloud storage operations list:

gcloud storage operations list gs://BUCKET_NAME

מחליפים את:

  • ‫BUCKET_NAME בשם הקטגוריה שמכילה את הפעולות הממושכות. לדוגמה, my-bucket.

ממשקי API ל-REST

API ל-JSON

  1. התקנה והפעלה של ה-CLI של gcloud, שמאפשרות ליצור אסימון גישה לכותרת Authorization.

  2. משתמשים ב- cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת operations.get:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations"

    מחליפים את:

    • ‫BUCKET_NAME בשם הקטגוריה שמשויכת לפעולות הממושכות שרוצים להציג ברשימה.

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

{
  "kind": "storage#operations",
  "nextPageToken": string,
  "operations": [
    operations Resource
  ]
}

ביטול פעולה ממושכת

המסוף

  1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.

    כניסה לדף Buckets

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

  3. לוחצים על הכרטיסייה פעולות.

  4. בשורה של הפעולה ארוכת הטווח, לוחצים על More options ואז על Cancel.

שורת הפקודה

כדי לבטל פעולה ממושכת, משתמשים בפקודה gcloud storage operations cancel:

gcloud storage operations cancel projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

מחליפים את:

  • ‫BUCKET_NAME בשם הקטגוריה שמכילה את הפעולה הממושכת. לדוגמה, my-bucket.

  • ‫OPERATION_ID עם המזהה של הפעולה הממושכת, שמוחזר בתגובה של השיטות שקוראים להן. לדוגמה, התגובה הבאה מוחזרת מקריאה ל-gcloud storage restore ומזהה הפעולה הממושכת הוא BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

ממשקי API ל-REST

API ל-JSON

  1. התקנה והפעלה של ה-CLI של gcloud, שמאפשרות ליצור אסימון גישה לכותרת Authorization.

  2. משתמשים ב- cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת operations.post:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"

    מחליפים את:

    • ‫BUCKET_NAME בשם הקטגוריה שמשויכת לפעולה הממושכת שרוצים לבטל.

    • ‫OPERATION_ID עם המזהה של הפעולה הממושכת, שמוחזר בתשובה של השיטות שאתם מפעילים. לדוגמה, התגובה הבאה מוחזרת מקריאה ל-gcloud storage restore ומזהה הפעולה הממושכת הוא BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

מטא-נתונים

לפעולות ארוכות טווח משויכים מטא-נתונים. נתוני המטא-נתונים הבאים מזהים מאפיינים של פעולה ממושכת:

  • שעת היצירה: השעה שבה נוצרה הפעולה הממושכת.

  • שעת סיום: השעה שבה הסתיימה הפעולה הממושכת.

  • זמן העדכון: הזמן שבו הפעולה הממושכת שונתה לאחרונה.

  • סוג: הקריאה ל-API שהפעילה את הפעולה הממושכת.

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

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

במסוף Google Cloud , אחוז ההתקדמות והמטא-נתונים של בקשת הביטול מוצגים בשדה Status.

טיפול בשגיאות

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

לדוגמה, אם תשלחו בקשה לשחזור בכמות גדולה של פריטים במחיקה עם יכולת שחזור, יוחזר קוד סטטוס של HTTP (200 OK) גם אם תתרחש שגיאה במהלך הפעולה. כדי לבדוק אם פעולת השחזור בכמות גדולה הצליחה, אפשר לאחזר את הסטטוס של הפעולה הממושכת.

שימו לב שממשקי ה-API של פעולות ממושכות (Get, ‏ List, ‏ Cancel) הם סינכרוניים ומחזירים שגיאות רגילות.