באמצעות 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
יוצרים את גוף הבקשה. הזינו את גוף ההודעה בהתאם לסוג התוכן 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 של הסשן שניתן להמשיך.מוסיפים את נתוני המקטע לגוף הבקשה. צרו מקטעים בכפולות של 256 KB (256 x 1,024 בייטים), מלבד המקטע הסופי שמשלים את ההעלאה. חשוב שגודל המקטע יהיה גדול ככל האפשר, כדי שההעלאה תהיה יעילה.
מוסיפים את כותרות ה-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
כדי לציין שהמיקום הנוכחי בקובץ לא ידוע. לדוגמה, הגדירו את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 sheets, 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
של הקובץ, וכך לשפר את יכולת הגילוי.
מידע נוסף על טקסט שאפשר להוסיף לאינדקס זמין במאמר ניהול מטא-נתונים של קבצים.