דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

**איור 1.** שלבים כלליים לשיטה file.download.

קריאה ל-files.download: כשהאפליקציה קוראת לשיטה download, היא מפעילה את בקשת ההורדה של קובץ מ-Drive API. מידע נוסף זמין במאמר הורדת קבצים.
בקשת הרשאות: הבקשה שולחת פרטי אימות ל-Drive API. אם האפליקציה שלכם דורשת קריאה ל-Drive API באמצעות אימות של משתמש שעדיין לא קיבל הרשאה, המשתמש יתבקש להיכנס לחשבון. האפליקציה מבקשת גם גישה עם היקפי הרשאות שאתם מציינים כשמגדירים את האימות.
התחלת ההורדה: נשלחת בקשה ל-Drive API כדי להתחיל את ההורדה של הקובץ. יכול להיות שהבקשה נשלחה אל Google Vids או אל תוכן אחר של Google Workspace.
התחלת פעולה ממושכת (LRO): מתחילה פעולה ממושכת שמנהלת את תהליך ההורדה.
החזרת פעולה בהמתנה: Drive API מחזיר פעולה בהמתנה שמכילה מידע על המשתמש ששולח את הבקשה וכמה שדות של מטא-נתונים של הקובץ.
מצב ראשוני בהמתנה: האפליקציה מקבלת את הפעולה בהמתנה יחד עם מצב ראשוני בהמתנה של done=null. המשמעות היא שהקובץ עדיין לא מוכן להורדה ושהסטטוס של הפעולה הוא בהמתנה.
הפעלת operations.get ואימות התוצאה: האפליקציה מפעילה את get במרווחי הזמן המומלצים כדי לדגום את תוצאת הפעולה ולקבל את הסטטוס העדכני של פעולה ממושכת. אם מוחזר הסטטוס 'בהמתנה' של done=false, האפליקציה צריכה להמשיך לשלוח בקשות עד שהפעולה תחזיר את הסטטוס 'הושלם' (done=true). כשמדובר בקבצים גדולים, צפויות כמה בקשות. מידע נוסף זמין במאמר בנושא קבלת פרטים על פעולה ממושכת.
בדיקת סטטוס ההמתנה: אם סטטוס ההמתנה של done=true מוחזר מ-LRO, המשמעות היא שהקובץ מוכן להורדה ושהסטטוס של הפעולה הוא 'הושלם'.
החזרת פעולה שהושלמה עם URI להורדה: אחרי שה-LRO מסתיים, Drive API מחזיר את ה-URI להורדה והקובץ זמין למשתמש.

הורדת קבצים

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

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

סוג המסמך	פורמט	סוג MIME	סיומת קובץ
Google Apps Script	JSON	application/vnd.google-apps.script+json	‫.json
Google Docs	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	‎.docx
Google Drawings	PNG	image/png	‎.png‎
Google Forms	ZIP	application/zip	.zip
Google Sheets	Microsoft Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	‎.xlsx‎
Google Sites	טקסט גולמי	טקסט/גולמי	‎.txt
Google Slides	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	‎.pptx
Google Vids	MP4	application/mp4	‎.mp4
Jamboard	PDF	application/pdf	‎.pdf‎

הורדת התשובה

כשמפעילים את השיטה 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.

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

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

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

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

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

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

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

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

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

הפעלת method

operations.get(name='NAME');

מחליפים את NAME בשם שהוקצה לפעולה על ידי השרת, כפי שמופיע בתגובה לבקשת ה-method‏ download.

curl

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

מחליפים את NAME בשם שהוקצה לפעולה על ידי השרת, כפי שמופיע בתגובה לבקשת ה-method‏ download.

הפקודה משתמשת בנתיב /drive/v3/operations/NAME.

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

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

כשפעולה ארוכת טווח נכשלת, התשובה שלה כוללת קוד שגיאה קנוני של Google Cloud.

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

מידע נוסף על מודל השגיאות הזה ועל אופן השימוש בו זמין ב-API Design Guide.

קוד	ספירה	קוד מצב HTTP	תיאור	הפעולה המומלצת
1	`CANCELLED`	`499 Client Closed Request`	הפעולה בוטלה, בדרך כלל על ידי המתקשר.	מריצים מחדש את הפעולה.
2	`UNKNOWN`	`500 Internal Server Error`	יכול להיות שהשגיאה הזו תוחזר כשערך `Status` שמתקבל ממרחב כתובות אחר שייך למרחב שגיאות שלא מוכר במרחב הכתובות הזה. אם שגיאת ה-API לא מחזירה מספיק מידע, יכול להיות שהשגיאה תומר לשגיאה הזו.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
3	`INVALID_ARGUMENT`	`400 Bad Request`	הלקוח ציין ארגומנט לא חוקי. השגיאה הזו שונה מהשגיאה `FAILED_PRECONDITION`. ‫`INVALID_ARGUMENT` מציין ארגומנטים בעייתיים ללא קשר למצב המערכת, כמו שם קובץ פגום.	אל תנסו שוב בלי לפתור את הבעיה.
4	`DEADLINE_EXCEEDED`	`504 Gateway Timeout`	המועד האחרון חלף לפני שהפעולה הסתיימה. בפעולות שמשנות את מצב המערכת, יכול להיות שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, יכול להיות שהתגובה המוצלחת משרת התעכבה מספיק זמן עד שהמועד האחרון חלף.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
5	`NOT_FOUND`	`404 Not Found`	לא נמצאה ישות מסוימת שנדרשה, כמו משאב FHIR.	אל תנסו שוב בלי לפתור את הבעיה.
6	`ALREADY_EXISTS`	`409 Conflict`	הישות שהלקוח ניסה ליצור, כמו מופע DICOM, כבר קיימת.	אל תנסו שוב בלי לפתור את הבעיה.
7	`PERMISSION_DENIED`	`403 Forbidden`	למתקשר אין הרשאה לבצע את הפעולה שצוינה. קוד השגיאה הזה לא מרמז שהבקשה תקפה, שהישות המבוקשת קיימת או שהיא עומדת בתנאים מוקדמים אחרים.	אל תנסו שוב בלי לפתור את הבעיה.
8	`RESOURCE_EXHAUSTED`	`429 Too Many Requests`	הגעתם למגבלת משאב מסוים, כמו מכסה לכל פרויקט.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). יכול להיות שהמכסה תהיה זמינה בהמשך.
9	`FAILED_PRECONDITION`	`400 Bad Request`	הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, או שפעולת `rmdir` מוחלת על פריט שהוא לא ספרייה.	אל תנסו שוב בלי לפתור את הבעיה.
10	`ABORTED`	`409 Conflict`	הפעולה בוטלה, בדרך כלל בגלל בעיה של פעולות מקבילות, כמו כשל בבדיקת רצף או ביטול עסקה.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
11	`OUT_OF_RANGE`	`400 Bad Request`	הניסיון לבצע את הפעולה היה מחוץ לטווח התקין, למשל ניסיון להגיע למיקום או לקרוא אחרי סוף הקובץ. בשונה מ-`INVALID_ARGUMENT`, השגיאה הזו מצביעה על בעיה שאולי תיפתר אם מצב המערכת ישתנה.	אל תנסו שוב בלי לפתור את הבעיה.
12	`UNIMPLEMENTED`	`501 Not Implemented`	הפעולה לא מיושמת או לא נתמכת/מופעלת ב-Drive API.	לא לנסות שוב.
13	`INTERNAL`	`500 Internal Server Error`	שגיאות פנימיות. השגיאה הזו מציינת שנתקלתם בשגיאה לא צפויה במהלך העיבוד במערכת הבסיסית.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
14	`UNAVAILABLE`	`503 Service Unavailable`	ממשק Drive API לא זמין. סביר להניח שמדובר במצב זמני, שאפשר לתקן אותו על ידי ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
15	`DATA_LOSS`	`500 Internal Server Error`	פגם בנתונים או אובדן נתונים שלא ניתן לשחזר.	צריך לפנות לאדמין. אם אירע אובדן נתונים או שהנתונים נפגמו, מנהל המערכת יכול לפנות לנציג תמיכה.
16	`UNAUTHENTICATED`	`401 Unauthorized`	בבקשה לא צוינו פרטי כניסה תקינים לאימות לצורך הפעולה.	אל תנסו שוב בלי לפתור את הבעיה.

הורדה וייצוא של קבצים