Google Drive API מאפשר להעלות נתוני קבצים כשיוצרים או מעדכנים
File
לקבלת מידע על האופן שבו ניתן ליצור
קובץ מטא-נתונים בלבד, כמו תיקייה, ראו יצירת קבצים של מטא-נתונים בלבד.
יש שלושה סוגי העלאות שאפשר לבצע:
העלאה פשוטה (
uploadType=media
): השתמשו בסוג ההעלאה הזה כדי להעביר קובץ מדיה קטן (עד 5MB) ללא ציון מטא-נתונים. כדי לבצע להעלאה פשוטה, קראו את המאמר ביצוע העלאה פשוטה.העלאה מרובת חלקים (
uploadType=multipart
): "יש להשתמש בסוג ההעלאה הזה כדי להעביר קובץ קטן (עד 5MB) ביחד עם מטא-נתונים שמתארים את בבקשה אחת. כדי לבצע העלאה מרובת חלקים, קראו את המאמר ביצוע העלאה מרובת חלקים.העלאה שניתן להמשיך (
uploadType=resumable
): צריך להשתמש בסוג ההעלאה הזה כדי קבצים גדולים (מעל 5MB) וכשיש סיכוי גבוה לרשת הפרעות, למשל, במהלך יצירת קובץ מאפליקציה לנייד. ניתן להמשיך הן גם אפשרות טובה לרוב האפליקציות, כי הן גם פועלות לקבצים קטנים בעלות מינימלית של בקשת HTTP אחת נוספת לכל העלאה. כדי לבצע העלאה שניתן להמשיך, קראו את המאמר ביצוע העלאה שניתן להמשיך upload.
ספריות הלקוח של 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 באורך התוכן, המוגדרת למספר הבייטים בקובץ.
- שולחים את הבקשה. אם בקשת ההעלאה נקטעת, או אם קיבלתם
התשובה
5xx
, מבצעים את התהליך שבקטע המשך העלאה שהופסקה.
HTTP – בקשות מרובות
יוצרים בקשת
PUT
ל-URI של הסשן שניתן להמשיך.מוסיפים את נתוני המקטע לגוף הבקשה. יצירת מקטעים בכפולות של גודל של 256KB (256x1,024 בייטים), מלבד המקטע הסופי שמשלים של ההעלאה. חשוב שגודל המקטע יהיה גדול ככל האפשר כדי שההעלאה תהיה יעיל.
מוסיפים את כותרות ה-HTTP הבאות:
Content-Length
מוגדר למספר הבייטים במקטע הנוכחי.Content-Range
מגדירים את הבייטים בקובץ שמעלים. עבור לדוגמה,Content-Range: bytes 0-524287/2000000
מראה שהעליתם את 524,288 הבייטים הראשונים (256x1,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 או גיליונות לדוגמה, אולי תרצו להמיר מסמך את מעבד התמלילים המועדף עליכם ב-Docs כדי לנצל לבינה מלאכותית גנרטיבית.
כדי להמיר קובץ לסוג קובץ ספציפי ב-Google Workspace, צריך לציין את
Google Workspace mimeType
בזמן יצירת הקובץ.
כך ממירים קובץ CSV לגיליון ב-Google Workspace:
Java
Python
Node.js
PHP
.NET
כדי לראות אם יש המרה זמינה, צריך לבדוק את המערך importFormats
של המשאב about
לפני שיוצרים את הקובץ.
ההמרות הנתמכות זמינות באופן דינמי במערך הזה. כמה דוגמאות
פורמטים של ייבוא הם:
מאת | אל |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, טקסט פשוט | Google Docs |
Microsoft Excel, OpenDocument sheet, CSV, TSV, טקסט פשוט | Google Sheets |
Microsoft PowerPoint, OpenDocument מצגת | 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
של הקובץ.
למידע נוסף על טקסט שניתן להוסיף לאינדקס, אפשר לעיין במאמר ניהול קובץ מטא-נתונים.