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

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

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

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

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

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

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

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

שלבים כלליים לשיטה file.download. — **איור 1.** סקירה כללית של השלבים לשימוש בשיטה file.download.

קריאה ל-files.download: כשהאפליקציה מפעילה את ה-method download(), היא מפעילה את בקשת ההורדה של Drive API של הקובץ. למידע נוסף, ראו הורדת קבצים.
בקשת הרשאות: הבקשה שולחת פרטי כניסה לאימות ל-Drive API. אם האפליקציה מחייבת קריאה ל-Drive API באמצעות אימות של המשתמש שעדיין לא ניתן, היא תבקש מהמשתמש להיכנס. האפליקציה מבקשת גישה גם באמצעות היקפי הרשאות שהגדרתם כשהגדרתם את האימות.
התחלת ההורדה: נשלחת בקשה ל-Drive API כדי להתחיל את הורדת הקובץ. אפשר לשלוח את הבקשה ל-Google Vids או לתוכן אחר ב-Google Workspace.
Start 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 שבו צריך להשתמש ב-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 שמוגדרים כברירת מחדל:

סוג המסמך	פורמט	סוג 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.

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

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

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

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

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

כדי לדגום LRO זמין, צריך להפעיל שוב ושוב את השיטה get() עד שהפעולה מסתיימת. משתמשים בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) בין כל בקשת סקירה, למשל 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 בשם שמוקצה על ידי השרת של הפעולה כפי שמוצג בתשובה לבקשת ה-method של download().

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

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

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

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

הורדת גרסה

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

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

קוד	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`	בבקשה לא צוינו פרטי כניסה תקינים לביצוע הפעולה.	אל תנסו שוב בלי לפתור את הבעיה.