Google Drive API מאפשר לכם להעלות נתוני קבצים כשאתם יוצרים או מעדכנים File. במאמר יצירת קבצים שמכילים רק מטא-נתונים מוסבר איך ליצור קובץ שמכיל רק מטא-נתונים, כמו תיקייה.
יש שלושה סוגים של העלאות שאפשר לבצע:
העלאה פשוטה (
uploadType=media): משתמשים בסוג ההעלאה הזה כדי להעביר קובץ מדיה קטן (5MB או פחות) בלי לספק מטא-נתונים. כדי לבצע העלאה פשוטה, אפשר לעיין במאמר ביצוע העלאה פשוטה.העלאה מרובת חלקים (
uploadType=multipart): "השתמשו בסוג ההעלאה הזה כדי להעביר קובץ קטן (5MB או פחות) יחד עם מטא-נתונים שמתארים את הקובץ, בבקשה אחת. כדי לבצע העלאה מרובת חלקים, אפשר לעיין במאמר בנושא ביצוע העלאה מרובת חלקים.העלאה שניתן להמשיך (
uploadType=resumable): משתמשים בסוג ההעלאה הזה לקבצים גדולים (מעל 5MB) וכשיש סיכוי גבוה להפרעה ברשת, למשל כשיוצרים קובץ מאפליקציה לנייד. העלאות שניתן להמשיך הן גם בחירה טובה לרוב האפליקציות, כי הן עובדות גם לקבצים קטנים בעלות מינימלית של בקשת HTTP אחת נוספת לכל העלאה. כדי לבצע העלאה שניתן להמשיך, אפשר לעיין במאמר הפעלת העלאה שניתן להמשיך.
ספריות הלקוח של Google API מטמיעות לפחות אחד מהסוגים האלה של העלאות. פרטים נוספים על אופן השימוש בכל אחד מהסוגים זמינים במסמכי התיעוד של ספריית הלקוח.
שימוש ב-PATCH לעומת PUT
תזכורת: פועל ה-HTTP PATCH תומך בעדכון חלקי של משאב קובץ, ואילו פועל ה-HTTP PUT תומך בהחלפה מלאה של משאב. שימו לב: יכול להיות ששימוש ב-PUT
יוביל לשינויים שעלולים לשבור את התאימות לאחור כשמוסיפים שדה חדש למשאב קיים.
כשמעלים משאב קובץ, חשוב לפעול לפי ההנחיות הבאות:
- משתמשים בפועל HTTP שמתועד בהפניה ל-API עבור הבקשה הראשונית של העלאה שניתן להמשיך, או עבור הבקשה היחידה של העלאה פשוטה או העלאה מרובת חלקים.
- אחרי שהבקשה מתחילה, משתמשים ב-
PUTבכל הבקשות הבאות להעלאה שניתן להמשיך. הבקשות האלה מעלות תוכן ללא קשר לשיטה שמופעלת.
ביצוע העלאה פשוטה
כדי לבצע העלאה פשוטה, משתמשים בשיטה create במשאב files עם uploadType=media.
בדוגמה הבאה אפשר לראות איך לבצע העלאה פשוטה:
HTTP
יוצרים בקשת
POSTל-URI של העלאה של השיטה, עם פרמטר השאילתהuploadType=media:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=mediaמוסיפים את נתוני הקובץ לגוף הבקשה.
מוסיפים את כותרות ה-HTTP הבאות:
-
Content-Type. צריך להגדיר את סוג המדיה MIME של האובייקט שמעלים. -
Content-Length. צריך להגדיר את הערך למספר הבייטים שמעלים. אם משתמשים בקידוד העברה במקטעים, לא צריך להוסיף את הכותרת הזו.
-
שולחים את הבקשה. אם הבקשה תתבצע בהצלחה, השרת יחזיר את קוד הסטטוס
HTTP 200 OKיחד עם המטא-נתונים של הקובץ. {HTTP}
כשמבצעים העלאה פשוטה, נוצרים מטא-נתונים בסיסיים וחלק מהמאפיינים מוסקים מהקובץ, כמו סוג ה-MIME או modifiedTime. אפשר להשתמש בהעלאה פשוטה במקרים שבהם יש קבצים קטנים ומטא-נתונים של קבצים לא חשובים.
ביצוע העלאה מרובת חלקים
בקשת העלאה מרובת חלקים מאפשרת להעלות מטא-נתונים ונתונים באותה בקשה. האפשרות הזו מתאימה אם הנתונים שאתם שולחים קטנים מספיק ואפשר להעלות אותם בשלמותם אם החיבור נכשל.
כדי לבצע העלאה מרובת חלקים, משתמשים ב-method create במשאב files עם uploadType=multipart.
כך מבצעים העלאה מרובת חלקים:
Java
Python
Node.js
PHP
.NET
HTTP
יוצרים בקשת
POSTל-URI של העלאה של השיטה, עם פרמטר השאילתהuploadType=multipart:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipartיוצרים את גוף הבקשה. הפורמט של גוף ההודעה צריך להיות תואם לסוג התוכן multipart/related RFC 2387, שמכיל שני חלקים:
- מטא-נתונים. המטא-נתונים צריכים להופיע ראשונים, והכותרת שלהם צריכה להיות
Content-Typeapplication/json;charset=UTF-8. מוסיפים את המטא-נתונים של הקובץ בפורמט JSON. - מדיה. המדיה צריכה להיות במקום השני, וחייבת להיות לה כותרת
Content-Typeמכל סוג MIME. מוסיפים את נתוני הקובץ לחלק של המדיה.
מזהים כל חלק באמצעות מחרוזת גבול, שלפניה שני מקפים. בנוסף, מוסיפים שני מקפים אחרי מחרוזת הגבול הסופית.
- מטא-נתונים. המטא-נתונים צריכים להופיע ראשונים, והכותרת שלהם צריכה להיות
מוסיפים את כותרות ה-HTTP הבאות ברמה העליונה:
-
Content-Type. מגדירים את הערךmultipart/relatedוכוללים את מחרוזת הגבול שבה משתמשים כדי לזהות את החלקים השונים של הבקשה. לדוגמה:Content-Type: multipart/related; boundary=foo_bar_baz -
Content-Length. הערך שמוגדר הוא המספר הכולל של הבייטים בגוף הבקשה.
-
שולחים את הבקשה.
כדי ליצור או לעדכן רק את חלק המטא-נתונים, בלי הנתונים המשויכים, שולחים בקשת POST או PATCH לנקודת הקצה של המשאב הרגיל: https://www.googleapis.com/drive/v3/files אם הבקשה מצליחה, השרת מחזיר את קוד הסטטוס HTTP 200 OK יחד עם המטא-נתונים של הקובץ.
כשיוצרים קבצים, צריך לציין סיומת קובץ בשדה name של הקובץ. לדוגמה, כשיוצרים קובץ JPEG של תמונה, אפשר לציין במטא-נתונים משהו כמו "name": "photo.jpg". קריאות חוזרות לשיטה get מחזירות את המאפיין fileExtension לקריאה בלבד שמכיל את התוסף שצוין במקור בשדה name.
ביצוע העלאה שניתן להמשיך
העלאה שניתן להמשיך מאפשרת לכם להמשיך פעולת העלאה אחרי שכשל בתקשורת מפריע לזרימת הנתונים. בגלל שאין צורך להפעיל מחדש מההתחלה העלאות של קבצים גדולים, העלאות שניתן להמשיך יכולות גם לצמצם את השימוש ברוחב הפס במקרה של תקלה ברשת.
העלאות שאפשר להמשיך אותן שימושיות כשגודלי הקבצים עשויים להשתנות מאוד או כשקיימת מגבלת זמן קבועה לבקשות (כמו משימות ברקע במערכת הפעלה לנייד ובקשות מסוימות של App Engine). אפשר להשתמש בהעלאות שניתן להמשיך גם במקרים שבהם רוצים להציג סרגל התקדמות של ההעלאה.
העלאה שניתן להמשיך מורכבת מכמה שלבים ברמה גבוהה:
- שולחים את הבקשה הראשונית ומאחזרים את ה-URI של הסשן שניתן להמשיך.
- מעלים את הנתונים ועוקבים אחרי סטטוס ההעלאה.
- (אופציונלי) אם ההעלאה נקטעת, ממשיכים אותה.
שליחת הבקשה הראשונית
כדי להתחיל העלאה שניתן להמשיך, משתמשים בשיטה create במשאב files עם uploadType=resumable.
HTTP
יוצרים בקשת
POSTל-URI של העלאה של השיטה, עם פרמטר השאילתהuploadType=resumable:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumableאם בקשת ההפעלה מצליחה, התשובה כוללת קוד סטטוס
200 OKשל HTTP. בנוסף, היא כוללת כותרתLocationשמציינת את ה-URI של הסשן שניתן להמשיך:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0שומרים את ה-URI של הסשן שניתן להמשיך כדי להעלות את נתוני הקובץ ולשאול על סטטוס ההעלאה. התוקף של ה-URI של סשן שניתן להמשיך יפוג אחרי שבוע.
אם יש לכם מטא-נתונים לקובץ, מוסיפים אותם לגוף הבקשה בפורמט JSON. אחרת, משאירים את גוף הבקשה ריק.
מוסיפים את כותרות ה-HTTP הבאות:
-
X-Upload-Content-Type. אופציונלי. מגדירים את סוג ה-MIME של נתוני הקובץ, שמועברים בבקשות הבאות. אם סוג ה-MIME של הנתונים לא מצוין במטא-נתונים או באמצעות הכותרת הזו, האובייקט מוצג כ-application/octet-stream. -
X-Upload-Content-Length. אופציונלי. הערך שמוגדר הוא מספר הבייטים של נתוני הקובץ, שמועברים בבקשות הבאות. -
Content-Type. חובה אם יש לכם מטא-נתונים לקובץ. הערך שמוגדר הואapplication/json;charset=UTF-8. -
Content-Length. חובה, אלא אם משתמשים בקידוד של העברה במקטעים. הערך שמוגדר הוא מספר הבייטים בגוף הבקשה הראשונית.
-
שולחים את הבקשה. אם בקשת הפעלת הסשן מצליחה, התשובה כוללת קוד סטטוס
200 OK HTTP. בנוסף, התשובה כוללת כותרתLocationשמציינת את ה-URI של הסשן שניתן להמשיך. משתמשים ב-URI של הסשן שניתן להמשיך כדי להעלות את נתוני הקובץ ולשאול על סטטוס ההעלאה. התוקף של ה-URI של סשן שניתן להמשיך יפוג אחרי שבוע.מעתיקים ושומרים את כתובת ה-URL של הסשן שאפשר להמשיך.
ממשיכים אל העלאת התוכן.
העלאת התוכן
יש שתי דרכים להעלות קובץ באמצעות סשן שניתן להמשיך:
- העלאת תוכן בבקשה אחת: כדאי להשתמש בגישה הזו אם אפשר להעלות את הקובץ בבקשה אחת, אם אין מגבלת זמן קבועה לבקשה אחת, או אם לא צריך להציג את אינדיקטור התקדמות ההעלאה. הגישה הזו היא הטובה ביותר כי היא דורשת פחות בקשות ומניבה ביצועים טובים יותר.
העלאת התוכן במספר מקטעים: כדאי להשתמש בגישה הזו אם אתם צריכים להפחית את כמות הנתונים שמועברת בבקשה אחת. יכול להיות שתצטרכו לצמצם את כמות הנתונים שמועברים אם יש מגבלת זמן קבועה לבקשות בודדות, כמו במקרים מסוימים של בקשות App Engine. הגישה הזו שימושית גם אם אתם צריכים לספק מחוון בהתאמה אישית כדי להציג את התקדמות ההעלאה.
HTTP – בקשה יחידה
- יוצרים
PUTבקשה ל-URI של הסשן שניתן להמשיך. - מוסיפים את נתוני הקובץ לגוף הבקשה.
- מוסיפים כותרת HTTP של Content-Length, שמוגדרת למספר הבייטים בקובץ.
- שולחים את הבקשה. אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג
5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.
HTTP – בקשות מרובות
יוצרים
PUTבקשה ל-URI של הסשן שניתן להמשיך.מוסיפים את נתוני החלק לגוף הבקשה. יוצרים מקטעים בגודל של כפולה של 256KB (כלומר, 256x1024 בייטים), למעט המקטע האחרון שמשלים את ההעלאה. כדאי להגדיר את גודל החלקים לגדול ככל האפשר כדי שההעלאה תהיה יעילה.
מוסיפים את כותרות ה-HTTP הבאות:
-
Content-Length. הערך שמוגדר הוא מספר הבייטים בחלק הנוכחי. -
Content-Range. ההגדרה הזו קובעת אילו בייטים בקובץ שהעליתם יוצגו. לדוגמה,Content-Range: bytes 0-524287/2000000מראה שהעליתם את 524,288 הבייטים הראשונים (256 x 1024 x 2) בקובץ בגודל 2,000,000 בייטים.
-
שולחים את הבקשה ומעבדים את התגובה. אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג
5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.חוזרים על שלבים 1 עד 4 לכל נתח שנשאר בקובץ. משתמשים בכותרת
Rangeבתגובה כדי לקבוע איפה להתחיל את החלק הבא. אל תניחו שהשרת קיבל את כל הבייטים שנשלחו בבקשה הקודמת.
כשההעלאה של הקובץ מסתיימת, מקבלים את התשובה 200 OK או 201 Created עם כל המטא-נתונים שמשויכים למשאב.
המשך העלאה שהופסקה
אם בקשת העלאה הופסקה לפני קבלת תשובה, או אם מקבלים תשובה מסוג 503
Service Unavailable, צריך להמשיך את ההעלאה שהופסקה.
HTTP
כדי לבקש את סטטוס ההעלאה, יוצרים בקשת
PUTריקה ל-URI של הסשן שניתן להמשך.הוספת כותרת
Content-Rangeכדי לציין שהמיקום הנוכחי בקובץ לא ידוע. לדוגמה, אם האורך הכולל של הקובץ הוא 2,000,000 בייטים, צריך להגדיר את הערךContent-Rangeל-*/2000000. אם לא יודעים מה הגודל המלא של הקובץ, צריך להגדיר אתContent-Rangeל-*/*.שולחים את הבקשה.
מעבדים את התשובה:
- התשובה
200 OKאו201 Createdמציינת שההעלאה הושלמה ולא צריך לבצע פעולה נוספת. - התשובה
308 Resume Incompleteמציינת שצריך להמשיך להעלות את הקובץ. - התשובה
404 Not Foundמציינת שתוקף סשן ההעלאה פג וצריך להתחיל את ההעלאה מחדש.
- התשובה
אם קיבלתם תגובה
308 Resume Incomplete, צריך לעבד את הכותרתRangeשל התגובה כדי לקבוע אילו בייטים התקבלו בשרת. אם התשובה לא כוללת את הכותרתRange, לא התקבלו בייטים. לדוגמה, כותרתRangeעם הערךbytes=0-42מציינת ש-43 הבייטים הראשונים של הקובץ התקבלו, והמקטע הבא שיועלה יתחיל בבייט 44.עכשיו, אחרי שיודעים מאיפה להמשיך את ההעלאה, ממשיכים להעלות את הקובץ החל מהבייט הבא. צריך לכלול כותרת
Content-Rangeכדי לציין איזה חלק מהקובץ אתם שולחים. לדוגמה,Content-Range: bytes 43-1999999מציין שאתם שולחים בייטים 44 עד 2,000,000.
טיפול בשגיאות בהעלאת מדיה
כשמעלים מדיה, כדאי לפעול לפי השיטות המומלצות הבאות כדי לטפל בשגיאות:
- במקרה של שגיאות
5xx, צריך להמשיך או לנסות שוב להעלות קבצים שההעלאה שלהם נכשלה בגלל שיבושים בחיבור. מידע נוסף על טיפול בשגיאות5xxזמין במאמר שגיאות 500, 502, 503 ו-504. - אם מופיעות שגיאות
403 rate limit, צריך לנסות להעלות שוב. מידע נוסף על טיפול בשגיאות403 rate limitזמין במאמר שגיאה 403:rateLimitExceeded. - אם מתקבלות שגיאות
4xx(כולל403) במהלך העלאה שניתן להמשיך, צריך להפעיל מחדש את ההעלאה. השגיאות האלה מציינות שתוקף הסשן של ההעלאה פג, וצריך להפעיל אותו מחדש על ידי בקשת URI חדש של סשן. התוקף של סשנים של העלאות יפוג גם הוא אחרי שבוע של חוסר פעילות.
ייבוא לסוגים של Google Docs
כשיוצרים קובץ ב-Drive, לפעמים רוצים להמיר אותו לסוג קובץ של Google Workspace, כמו Google Docs או Sheets. לדוגמה, יכול להיות שתרצו להמיר מסמך ממעבד התמלילים המועדף שלכם ל-Docs כדי ליהנות מהתכונות שלו.
כדי להמיר קובץ לסוג קובץ ספציפי של Google Workspace, צריך לציין את mimeType של Google Workspace כשיוצרים את הקובץ.
ההוראות הבאות מראות איך להמיר קובץ CSV לגיליון אלקטרוני של Google Workspace:
Java
Python
Node.js
PHP
.NET
כדי לבדוק אם המרה זמינה, צריך לעיין בשדה importFormats של המשאב about לפני שיוצרים את הקובץ. המרות נתמכות זמינות באופן דינמי במערך הזה. חלק מהפורמטים הנפוצים לייבוא:
| מאת | אל |
|---|---|
| Microsoft Word, OpenDocument Text, HTML, RTF, טקסט פשוט | Google Docs |
| Microsoft Excel, OpenDocument Spreadsheet, CSV, TSV, טקסט פשוט | Google Sheets |
| Microsoft PowerPoint, OpenDocument Presentation | Google Slides |
| JPEG, PNG, GIF, BMP, PDF | Google Docs (התמונה מוטמעת במסמך) |
| טקסט פשוט (סוג MIME מיוחד), JSON | Google Apps Script |
כשמעלים וממירים מדיה במהלך update בקשה לקובץ Docs, Sheets או Slides, התוכן המלא של המסמך מוחלף.
כשממירים תמונה ל-Docs, Drive משתמש בזיהוי תווים אופטי (OCR) כדי להמיר את התמונה לטקסט. כדי לשפר את האיכות של אלגוריתם ה-OCR, צריך לציין את קוד השפה הרלוונטי של BCP
47 בפרמטר ocrLanguage.
הטקסט שחולץ מופיע במסמך לצד התמונה המוטמעת.
שימוש במזהה שנוצר מראש להעלאת קבצים
Drive API מאפשר לאחזר רשימה של מזהי קבצים שנוצרו מראש, שאפשר להשתמש בהם כדי ליצור, להעתיק ולהעלות משאבים. מידע נוסף זמין במאמר בנושא יצירת מזהים לשימוש בקבצים.
אם מתרחשת שגיאת שרת לא מוגדרת או פסק זמן, אפשר לנסות שוב להעלות את הנתונים עם מזהים שנוצרו מראש. אם הפעולה על הקובץ מצליחה, ניסיונות חוזרים נוספים יחזירו קוד סטטוס 409 Conflict של HTTP ולא ייצרו קבצים כפולים.
שימו לב: אי אפשר להשתמש במזהים שנוצרו מראש כדי ליצור קבצים ב-Google Workspace, למעט application/vnd.google-apps.drive-sdkוapplication/vnd.google-apps.folder סוגי MIME. באופן דומה, אין תמיכה בהעלאות שמתייחסות להמרה לפורמט קובץ של Google Workspace.
הגדרת טקסט שניתן להוספה לאינדקס עבור סוגי קבצים לא ידועים
המשתמשים יכולים להשתמש בממשק המשתמש של Drive כדי למצוא תוכן במסמך. אפשר גם להשתמש בשיטה list במשאב files ובשדה fullText כדי לחפש תוכן מהאפליקציה. מידע נוסף זמין במאמר חיפוש קבצים ותיקיות.
Drive יוצר באופן אוטומטי אינדקס של מסמכים לחיפוש כשהוא מזהה את סוג הקובץ, כולל מסמכי טקסט, קובצי PDF, תמונות עם טקסט וסוגים נפוצים אחרים. אם האפליקציה שומרת סוגים אחרים של קבצים (כמו ציורים, סרטונים וקיצורי דרך), אפשר לשפר את יכולת הגילוי שלהם על ידי הוספת טקסט שאפשר להוסיף לאינדקס בשדה contentHints.indexableText של הקובץ.
מידע נוסף על טקסט שאפשר להוסיף לאינדקס זמין במאמר ניהול מטא-נתונים של קבצים.