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

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

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

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

השיטה מחזירה ללקוח משאב 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.
התחלת LRO: מתחילה פעולה ממושכת שמנהלת את תהליך ההורדה.
החזרת פעולה בהמתנה: ‏Drive API מחזיר פעולה בהמתנה שמכילה מידע על המשתמש ששלח את הבקשה וכמה שדות של מטא-נתונים של הקובץ.
מצב התחלתי בהמתנה: האפליקציה מקבלת את הפעולה בהמתנה יחד עם מצב התחלתי בהמתנה של done=null. המשמעות היא שהקובץ עדיין לא מוכן להורדה וסטטוס הפעולה הוא בהמתנה.
קריאה ל-operations.get ואימות התוצאה: האפליקציה קוראת ל-get() במרווחי הזמן המומלצים כדי לדגום את תוצאת הפעולה ולקבל את המצב העדכני של פעולה ממושכת. אם הסטטוס done=false בהמתנה מוחזר, האפליקציה צריכה להמשיך לבצע סקרים עד שהפעולה תחזיר את הסטטוס done=true (הושלם). לגבי קבצים גדולים, צפוי שתצטרכו לבצע סקרים כמה פעמים. מידע נוסף זמין במאמר קבלת פרטים על פעולה ממושכת.
בדיקת המצב 'בהמתנה': אם המצב 'בהמתנה' של done=true מוחזר מה-LRO, סימן שהקובץ מוכן להורדה וסטטוס הפעולה הושלם.
החזרת פעולה שהושלמו עם 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 שמוגדרים כברירת מחדל:

סוג המסמך	פורמט	סוג 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	טקסט גולמי	text/raw	‎.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.

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

השיטה 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 בשם שהוקצה לשרת של הפעולה, כפי שמוצג בתגובה לבקשת השיטה download().

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

הערה: השדה 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.

קוד	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`	ממשק ה-API של Drive לא זמין. סביר להניח שמדובר במצב זמני, שאפשר לתקן על ידי ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). חשוב לזכור שלא תמיד בטוח לבצע ניסיונות חוזרים של פעולות שהן לא אידמפוטנטיות.	ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
15	`DATA_LOSS`	אובדן נתונים או פגיעה בנתונים שלא ניתן לשחזר.	פונים למנהל המערכת. אם אירעו אובדן נתונים או פגיעה בנתונים, מנהל המערכת יכול לפנות לנציג תמיכה.
16	`UNAUTHENTICATED`	בבקשה לא צוינו פרטי כניסה תקינים לביצוע הפעולה.	אל תנסו שוב בלי לפתור את הבעיה.