באמצעות 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
בכל הבקשות הבאות להעלאה שניתן להמשיך. הבקשות האלה מעלות תוכן ללא קשר לשיטה שנקראת.
ביצוע העלאה פשוטה
כדי לבצע העלאה פשוטה, משתמשים בשיטה files.create
עם uploadType=media
.
כך מבצעים העלאה פשוטה:
HTTP
יוצרים בקשת
POST
למזהה ה-URI /upload של השיטה עם פרמטר השאילתה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
. אפשר להשתמש בהעלאה פשוטה במקרים שבהם יש קבצים קטנים והמטא-נתונים של הקובץ לא חשובים.
ביצוע העלאה מרובת חלקים
בקשת העלאה מרובת חלקים מאפשרת להעלות מטא-נתונים ונתונים באותה בקשה. האפשרות הזו מתאימה אם הנתונים שאתם שולחים קטנים מספיק ואפשר להעלות אותם שוב, בשלמותם, אם החיבור נכשל.
כדי לבצע העלאה מרובת חלקים, משתמשים בשיטה files.create
עם uploadType=multipart
.
כך מבצעים העלאה מרובת חלקים:
Java
Python
Node.js
PHP
.NET
HTTP
יוצרים בקשת
POST
למזהה ה-URI /upload של השיטה עם פרמטר השאילתהuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
יוצרים את גוף הבקשה. מעצבים את הגוף בהתאם לסוג התוכן multipart/related RFC 2387, שמכיל שני חלקים:
- מטא-נתונים. המטא-נתונים חייבים להופיע קודם, וחייבת להיות להם כותרת
Content-Type
שמוגדרת כ-application/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"
. קריאות חוזרות ל-files.get
מחזירות את המאפיין fileExtension
לקריאה בלבד שמכיל את התוסף שצוין במקור בשדה name
.
ביצוע העלאה שניתן להמשיך
העלאה שניתן להמשיך מאפשרת להמשיך פעולת העלאה אחרי שכשל בתקשורת מפריע לזרימת הנתונים. מכיוון שאין צורך להפעיל מחדש מההתחלה העלאות של קבצים גדולים, העלאות שניתן להמשיך יכולות גם לצמצם את השימוש ברוחב הפס במקרה של תקלה ברשת.
העלאות שניתן להמשיך אותן הן שימושיות כשגודל הקבצים עשוי להשתנות במידה רבה, או כשיש מגבלה זמן קבועה לבקשות (למשל, משימות רקע של מערכת הפעלה לנייד ובקשות מסוימות של App Engine). אפשר גם להשתמש בהעלאות שניתן להמשיך במקרים שבהם רוצים להציג סרגל התקדמות של ההעלאה.
העלאה שניתן להמשיך אותה מורכבת מכמה שלבים ברמה גבוהה:
- שולחים את הבקשה הראשונית ומאחזרים את ה-URI של הסשן שניתן להמשיך.
- מעלים את הנתונים ומנטרים את סטטוס ההעלאה.
- (אופציונלי) אם ההעלאה מופרעת, ממשיכים בהעלאה.
שליחת הבקשה הראשונית
כדי להתחיל העלאה שניתן להמשיך, משתמשים בשיטה files.create
עם uploadType=resumable
.
HTTP
יוצרים בקשת
POST
למזהה ה-URI /upload של השיטה עם פרמטר השאילתהuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
אם בקשת ההתחלה תתבצע בהצלחה, התשובה תכלול קוד סטטוס HTTP
200 OK
. בנוסף, היא כוללת כותרת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 (256 x 1,024 בייטים), מלבד המקטע האחרון שמסיים את ההעלאה. מומלץ להגדיר את גודל הקטעים הגדול ככל האפשר כדי שההעלאה תהיה יעילה.
מוסיפים את כותרות ה-HTTP הבאות:
Content-Length
. מוגדר למספר הבייטים בחלק הנוכחי.Content-Range
. מגדירים אילו ביטים בקובץ ייכללו בהעלאה. לדוגמה,Content-Range: bytes 0-524287/2000000
מראה שהעליתם את 524,288 הבייטים הראשונים (256 x 1,024 x 2) בקובץ של 2,000,000 בייטים.
שולחים את הבקשה ומעבדים את התגובה. אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג
5xx
, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.חוזרים על שלבים 1 עד 4 לכל מקטע שנשאר בקובץ. משתמשים בכותרת
Range
בתגובה כדי לקבוע איפה להתחיל את החלק הבא. אל תניחו שהשרת קיבל את כל הבייטים שנשלחו בבקשה הקודמת.
כשההעלאה של הקובץ כולו מסתיימת, מקבלים את התשובה 200 OK
או 201 Created
עם כל המטא-נתונים שמשויכים למשאב.
המשך העלאה שהופסקה
אם בקשת העלאה הופסקה לפני קבלת תשובה, או אם מקבלים תשובה מסוג 503
Service Unavailable
, צריך להמשיך את ההעלאה שהופסקה.
HTTP
כדי לבקש את סטטוס ההעלאה, יוצרים בקשת
PUT
ריקה למזהה ה-URI של הסשן שניתן להמשיך.מוסיפים כותרת
Content-Range
כדי לציין שהמיקום הנוכחי בקובץ לא ידוע. לדוגמה, מגדירים אתContent-Range
כ-*/2000000
אם אורך הקובץ הכולל הוא 2,000,000 בייטים. אם לא יודעים מה הגודל המלא של הקובץ, מגדירים את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
. הטקסט שחולץ מופיע ב-Doc לצד התמונה המוטמעת.
שימוש במזהה שנוצר מראש כדי להעלות קבצים
באמצעות Drive API אפשר לאחזר רשימה של מזהי קבצים שנוצרו מראש, המשמשים להעלאה וליצירה של משאבים. אפשר להשתמש במזהים האלה שנוצרו מראש בבקשות להעלאה ובבקשות ליצירת קבצים. מגדירים את השדה id
במטא-נתונים של הקובץ.
כדי ליצור מזהים שנוצרו מראש, צריך להפעיל את הפונקציה files.generateIds
עם מספר המזהים שרוצים ליצור.
אם אירעה שגיאה לא ידועה בשרת או פג תוקף הזמן הקצוב, אפשר לנסות שוב להעלות את הנתונים עם מזהים שנוצרו מראש. אם הקובץ נוצר בהצלחה, ניסיונות חוזרים יחזירו את השגיאה HTTP 409
ולא ייווצרו קבצים כפולים.
הגדרת טקסט שאפשר להוסיף לאינדקס עבור סוגי קבצים לא מוכרים
המשתמשים יכולים להשתמש בממשק המשתמש של Drive כדי למצוא תוכן של מסמכים. אפשר גם להשתמש ב-files.list
ובשדה fullText
כדי לחפש תוכן מהאפליקציה. מידע נוסף זמין במאמר חיפוש קבצים ותיקיות.
כשמערכת Drive מזהה את סוג הקובץ, היא מוסיפה אותו באופן אוטומטי לאינדקס החיפוש. המערכת מזהה מסמכי טקסט, קובצי PDF, תמונות עם טקסט וסוגים נפוצים אחרים. אם האפליקציה שומרת סוגים אחרים של קבצים (כמו ציורים, סרטונים ומקשי קיצור), אפשר לשפר את החשיפה שלהם על ידי הוספת טקסט שאפשר להוסיף לאינדקס בשדה contentHints.indexableText
בקובץ.
מידע נוסף על טקסט שאפשר להוסיף לאינדקס זמין במאמר ניהול המטא-נתונים של הקבצים.