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

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

Google Drive API מחזיר LRO בכל פעם שמפעילים את השיטה download() במשאב files כדי להוריד את התוכן של קובץ, דרך Drive API או דרך ספריות הלקוח שלו.

השיטה מחזירה ללקוח משאב operations. אפשר להשתמש במשאב operations כדי לאחזר את הסטטוס של שיטת ה-API באופן אסינכרוני, על ידי דגימת הפעולה באמצעות השיטה get(). ה-LROs ב-Drive API פועלים בהתאם ל תבנית התכנון של LRO ב-Google Cloud.

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

סקירה כללית של התהליך

בתרשים הבא מוצגים השלבים הכלליים של אופן הפעולה של השיטה file.download.

1. קריאה ל-files.download: כשהאפליקציה קוראת ל-method‏ download(), היא מפעילה את בקשת ההורדה של הקובץ ב-Drive API. למידע נוסף, ראו הורדת קבצים.

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

3. התחלת ההורדה: נשלחת בקשה ל-Drive API כדי להתחיל את הורדת הקובץ. אפשר לשלוח את הבקשה ל-Google Vids או לתוכן אחר ב-Google Workspace.

4. התחלת LRO: מתחילה פעולה ממושכת שמנהלת את תהליך ההורדה.

5. החזרת פעולה בהמתנה: ‏Drive API מחזיר פעולה בהמתנה שמכילה מידע על המשתמש ששלח את הבקשה וכמה שדות של מטא-נתונים של הקובץ.

6. מצב התחלתי בהמתנה: האפליקציה מקבלת את הפעולה בהמתנה יחד עם מצב התחלתי בהמתנה של done=null. המשמעות היא שהקובץ עדיין לא מוכן להורדה וסטטוס הפעולה הוא בהמתנה.

7. קריאה ל-operations.get ואימות התוצאה: האפליקציה קוראת ל-get() במרווחי הזמן המומלצים כדי לדגום את תוצאת הפעולה ולקבל את המצב העדכני של פעולה ממושכת. אם הסטטוס done=false בהמתנה מוחזר, האפליקציה צריכה להמשיך לבצע סקרים עד שהפעולה תחזיר את הסטטוס done=true (הושלם). לגבי קבצים גדולים, צפוי שתצטרכו לבצע סקרים כמה פעמים. מידע נוסף זמין במאמר קבלת פרטים על פעולה ממושכת.

8. בדיקת המצב 'בהמתנה': אם המצב 'בהמתנה' של done=true מוחזר מה-LRO, סימן שהקובץ מוכן להורדה וסטטוס הפעולה הושלם.

9. החזרת הפעולה שהושלמו עם מזהה URI להורדה: אחרי שה-LRO מסתיים, ה-Drive API מחזיר את מזהה ה-URI להורדה והקובץ זמין עכשיו למשתמש.

הורדת קבצים

כדי להוריד תוכן במסגרת פעולה ממושכת, משתמשים ב-method‏ download() במשאב files. השיטה מקבלת את פרמטרי השאילתה file_id,‏ mime_type ו-revision_id:

• חובה. פרמטר השאילתה file_id הוא המזהה של הקובץ שרוצים להוריד.

• זה שינוי אופציונלי. פרמטר השאילתה mime_type מציין את סוג ה-MIME שבו צריך להשתמש ב-method. הוא זמין רק כשמורידים תוכן מדיה שאינו blob (כמו מסמכים ב-Google Workspace). רשימה מלאה של סוגי ה-MIME הנתמכים מופיעה במאמר ייצוא סוגי MIME למסמכים ב-Google Workspace.

  אם סוג ה-MIME לא מוגדר, מסמך Google Workspace יורד עם סוג MIME שמוגדר כברירת מחדל. מידע נוסף זמין במאמר סוגי MIME שמוגדרים כברירת מחדל.

• זה שינוי אופציונלי. פרמטר השאילתה revision_id הוא מזהה הגרסה של הקובץ שרוצים להוריד. האפשרות הזו זמינה רק כשמורידים קובצי blob, מסמכים של Google Docs וקבצים של Google Sheets. המערכת מחזירה את קוד השגיאה INVALID_ARGUMENT כשמורידים גרסה ספציפית של קבצים שלא נתמכים.

השיטה download() היא הדרך היחידה להורדת קובצי Vids בפורמט MP4, והיא בדרך כלל מתאימה ביותר להורדת רוב קובצי הווידאו.

קישורי ההורדה שנוצרו ל-Google Docs או ל-Sheets מחזירים בהתחלה הפניה אוטומטית. לוחצים על הקישור החדש כדי להוריד את הקובץ.

גם בבקשה לשיטה download() שמתחילה את ה-LRO וגם בבקשה לאחזור ה-URI הסופי להורדה, צריך להשתמש במפתחות משאבים. מידע נוסף זמין במאמר גישה לקבצים ב-Drive ששותפו באמצעות קישור באמצעות מפתחות משאבים.

כאן מוצג פרוטוקול הבקשה.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

מחליפים את FILE_ID ב-fileId של הקובץ שרוצים להוריד.

סוגי MIME שמוגדרים כברירת מחדל

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

הורדת התשובה

כשקוראים לשיטה download(), גוף התגובה מורכב ממשאב שמייצג פעולה ממושכת. בדרך כלל, השיטה מחזירה קישור להורדת תוכן הקובץ.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

הפלט הזה כולל את הערכים הבאים:

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

• NAME: השם שהוקצה על ידי השרת.

• DOWNLOAD_URI: ה-URI הסופי של הקובץ להורדה.

הערה: השדה partialDownloadAllowed מציין אם מותר לבצע הורדה חלקית. הערך True מופיע כשמורידים תוכן של קובץ blob.

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

פעולות ממושכות הן קריאות ל-method שעשויות להימשך זמן רב. בדרך כלל, פעולות הורדה חדשות שנוצרות מוחזרות בהתחלה במצב בהמתנה (done=null), במיוחד לגבי קובצי Vids.

אפשר להשתמש במשאב operations ש-Drive API מספק כדי לבדוק את הסטטוס של LRO לעיבוד, על ידי ציון השם הייחודי שהוקצה על ידי השרת.

השיטה get() מקבלת את המצב העדכני ביותר של פעולה ממושכת באופן אסינכרוני. לקוחות יכולים להשתמש ב-method הזה כדי לדגום את תוצאת הפעולה במרווחי זמן לפי ההמלצה של שירות ה-API.

דגימה של פעולה ממושכת

כדי לדגום LRO זמין, צריך להפעיל שוב ושוב את השיטה get() עד שהפעולה מסתיימת. משתמשים בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) בין כל בקשת סקירה, למשל 10 שניות.

LRO נשאר זמין למשך 12 שעות לפחות, אבל במקרים מסוימים הוא יכול להישאר למשך זמן ארוך יותר. משך הזמן הזה עשוי להשתנות, והוא יכול להיות שונה בין סוגי הקבצים. לאחר שתוקף המשאב יפוג, תצטרכו לשלוח בקשה חדשה לשיטה download().

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

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

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

הערה: השדה name מוחזר רק בתגובה לבקשה מסוג download(). אין דרך אחרת לאחזר אותו כי אין תמיכה בשיטה List() ב-Drive API. אם הערך של name אבד, צריך ליצור תשובה חדשה על ידי קריאה חוזרת לבקשת השיטה download().

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

כשהתגובה מכילה סטטוס של סיום (done=true), הפעולה הממושכת הסתיימה.

הורדת גרסה

אפשר להשתמש בערך של השדה headRevisionId מהמשאב files כדי להוריד את הגרסה האחרונה. הפעולה הזו מאחזרת את הגרסה שתואמת למטא-נתונים של הקובץ שאחזרתם קודם. כדי להוריד את הנתונים של כל הגרסאות הקודמות של הקובץ שעדיין שמורות בענן, אפשר להפעיל את השיטה list() במשאב revisions עם הפרמטר fileId. הפונקציה מחזירה את כל הערכים של revisionIds בקובץ.

כדי להוריד את תוכן הגרסה של קובצי blob, צריך להפעיל את השיטה get() במשאב revisions עם המזהה של הקובץ להורדה, המזהה של הגרסה ופרמטר כתובת ה-URL alt=media. פרמטר ה-URL alt=media מורה לשרת שמתבצעת בקשה להורדת תוכן כפורמט תגובה חלופי.

אי אפשר להוריד גרסאות מתוקנות של Google Docs‏, Sheets‏, Slides ו-Vids באמצעות השיטה get() עם כתובת ה-URL alt=media . אחרת, תופיע הודעת השגיאה fileNotDownloadable.

פרמטר כתובת ה-URL alt=media הוא פרמטר מערכת שזמין בכל ממשקי ה-API ל-REST של Google. אם אתם משתמשים בספריית לקוח של Drive API, אתם לא צריכים להגדיר את הפרמטר הזה באופן מפורש.

כאן מוצג פרוטוקול הבקשה.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

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

• FILE_ID: ה-fileId של הקובץ שרוצים להוריד.
• REVISION_ID: ה-revisionId של הגרסה שרוצים להוריד.

בגרסאות של Google Docs, ‏ Drawings ו-Slides, מספרי הגרסאות עולים אוטומטית. עם זאת, יכול להיות שיהיו פערים בסדרת המספרים אם גרסאות מתוקנות יימחקו, לכן לא כדאי להסתמך על מספרים רצופים כדי לאחזר גרסאות מתוקנות.

פתרון בעיות ב-LROs

כש-LRO נכשל, התגובה שלו כוללת קוד שגיאה קנוני של Google Cloud.

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

מידע נוסף על מודל השגיאות הזה ועל אופן השימוש בו זמין במדריך לעיצוב API.

נושאים קשורים

• הורדה וייצוא של קבצים
• ניהול גרסאות של קבצים