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
אם בקשת ההפעלה מצליחה, התשובה כוללת קוד סטטוס
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 מאפשר לכם לאחזר רשימה של מזהי קבצים שנוצרו מראש ומשמשים להעלאה וליצירה של משאבים. אפשר להשתמש במזהים שנוצרו מראש כדי להעלות קבצים או ליצור אותם. מגדירים את השדה id
במטא-נתונים של הקובץ.
כדי ליצור מזהים שנוצרו מראש, קוראים ל-files.generateIds
עם מספר המזהים שרוצים ליצור.
אם מתרחשת שגיאת שרת לא מוגדרת או פסק זמן, אפשר לנסות שוב להעלות את המזהים שנוצרו מראש. אם הקובץ נוצר בהצלחה, ניסיונות חוזרים ליצור אותו יחזירו שגיאה HTTP 409
ולא ייצרו קבצים כפולים.
הגדרת טקסט שניתן להוספה לאינדקס עבור סוגי קבצים לא ידועים
המשתמשים יכולים להשתמש בממשק המשתמש של Drive כדי למצוא תוכן של מסמך. אפשר גם להשתמש בfiles.list
ובשדה fullText
כדי לחפש תוכן מהאפליקציה. מידע נוסף זמין במאמר בנושא חיפוש קבצים ותיקיות.
Drive יוצר באופן אוטומטי אינדקס של מסמכים לחיפוש כשהוא מזהה את סוג הקובץ, כולל מסמכי טקסט, קובצי PDF, תמונות עם טקסט וסוגים נפוצים אחרים. אם האפליקציה שומרת סוגים אחרים של קבצים (כמו ציורים, סרטונים וקיצורי דרך), אפשר לשפר את יכולת הגילוי שלהם על ידי הוספת טקסט שניתן לאינדוקס בשדה contentHints.indexableText
של הקובץ.
מידע נוסף על טקסט שאפשר להוסיף לאינדקס זמין במאמר ניהול מטא-נתונים של קבצים.