דף זה תורגם על ידי 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, המשמעות היא שהקובץ מוכן להורדה ושהסטטוס של הפעולה הוא complete.
החזרת פעולה שהושלמה עם URI להורדה: אחרי שה-LRO מסתיים, Drive API מחזיר את ה-URI להורדה והקובץ זמין למשתמש.

הורדת קבצים

כדי להוריד תוכן במסגרת פעולה ממושכת, משתמשים ב-method‏ download במשאב files. השיטה מקבלת את פרמטרים של השאילתה 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 בשם שהוקצה לפעולה על ידי השרת, כפי שמופיע בתגובה לבקשת השיטה download.

curl

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

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

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

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

קוד	Enum	תיאור	הפעולה המומלצת
1	`CANCELLED`	הפעולה בוטלה, בדרך כלל על ידי המתקשר.	מריצים מחדש את הפעולה.
2	`UNKNOWN`	יכול להיות שהשגיאה הזו תוחזר כשערך `Status` שמתקבל ממרחב כתובות אחר שייך למרחב שגיאות שלא מוכר במרחב הכתובות הזה. אם שגיאת ה-API לא מחזירה מספיק מידע, יכול להיות שהשגיאה תומר לשגיאה הזו.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
3	`INVALID_ARGUMENT`	הלקוח ציין ארגומנט לא חוקי. השגיאה הזו שונה מהשגיאה `FAILED_PRECONDITION`. `INVALID_ARGUMENT` מציין ארגומנטים בעייתיים ללא קשר למצב המערכת, כמו שם קובץ פגום.	אל תנסו שוב בלי לפתור את הבעיה.
4	`DEADLINE_EXCEEDED`	המועד האחרון חלף לפני שהפעולה הסתיימה. בפעולות שמשנות את מצב המערכת, יכול להיות שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, יכול להיות שהתגובה המוצלחת משרת התעכבה מספיק זמן עד שהמועד האחרון חלף.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
5	`NOT_FOUND`	לא נמצאה ישות מסוימת שנדרשה, כמו משאב FHIR.	אל תנסו שוב בלי לפתור את הבעיה.
6	`ALREADY_EXISTS`	הישות שהלקוח ניסה ליצור, כמו מופע DICOM, כבר קיימת.	אל תנסו שוב בלי לפתור את הבעיה.
7	`PERMISSION_DENIED`	למתקשר אין הרשאה לבצע את הפעולה שצוינה. קוד השגיאה הזה לא מרמז שהבקשה תקפה, שהישות המבוקשת קיימת או שהיא עומדת בתנאים מוקדמים אחרים.	אל תנסו שוב בלי לפתור את הבעיה.
8	`RESOURCE_EXHAUSTED`	הגעתם למגבלת משאב מסוים, כמו מכסה לכל פרויקט.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). יכול להיות שהמכסה תגדל עם הזמן.
9	`FAILED_PRECONDITION`	הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, או שפעולת `rmdir` מוחלת על פריט שהוא לא ספרייה.	אל תנסו שוב בלי לפתור את הבעיה.
10	`ABORTED`	הפעולה בוטלה, בדרך כלל בגלל בעיה של פעולות מקבילות, כמו כשל בבדיקת רצף או ביטול עסקה.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
11	`OUT_OF_RANGE`	הניסיון לבצע את הפעולה היה מחוץ לטווח התקין, למשל ניסיון להגיע למיקום או לקרוא אחרי סוף הקובץ. בשונה מ-`INVALID_ARGUMENT`, השגיאה הזו מצביעה על בעיה שאולי תיפתר אם מצב המערכת ישתנה.	אל תנסו שוב בלי לפתור את הבעיה.
12	`UNIMPLEMENTED`	הפעולה לא מיושמת או לא נתמכת/מופעלת ב-Drive API.	לא לנסות שוב.
13	`INTERNAL`	שגיאות פנימיות. השגיאה הזו מציינת שנתקלתם בשגיאה לא צפויה במהלך העיבוד במערכת הבסיסית.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
14	`UNAVAILABLE`	ממשק Drive API לא זמין. סביר להניח שמדובר במצב זמני, שאפשר לתקן אותו על ידי ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
15	`DATA_LOSS`	פגם בנתונים או אובדן נתונים שלא ניתן לשחזר.	צריך לפנות לאדמין. אם אירע אובדן נתונים או שהנתונים נפגמו, מנהל המערכת יכול ליצור קשר עם נציג תמיכה.
16	`UNAUTHENTICATED`	בבקשה לא צוינו פרטי כניסה תקינים לאימות לצורך הפעולה.	אל תנסו שוב בלי לפתור את הבעיה.

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