בדף הזה מוסבר איך ליצור בקשת העלאה שניתן להמשיך ל-Google Photos Library API דרך פרוטוקול REST. הפרוטוקול הזה מאפשר להמשיך את פעולת ההעלאה אחרי שכשל בתקשורת מפריע לזרימת הנתונים.
כדאי להשתמש באפשרות ההעלאה שניתן להמשיך אם:
- אתם מעלים קבצים גדולים.
- יש סיכוי גבוה להפרעה ברשת או לכשל אחר בהעברה (לדוגמה, אם מעלים קובץ מאפליקציה לנייד).
העלאות שניתן להמשיך יכולות גם לצמצם את השימוש ברוחב הפס כשיש תקלה ברשת, כי לא צריך להפעיל מחדש העלאות של קבצים גדולים מההתחלה.
שלב 1: התחלת סשן העלאה
כדי להתחיל סשן העלאה שניתן להמשיך, שולחים בקשת POST אל https://photoslibrary.googleapis.com/v1/uploads. מעלים את הקובץ באמצעות כתובת ה-URL להעלאה שניתן להמשיך אותה שמוחזרת בבקשה הזו.
בקשת ה-POST חייבת לכלול את הכותרות הבאות:
| שדות כותרת | |
|---|---|
Content-Length |
מגדירים את הערך 0 כי גוף הבקשה ריק. |
X-Goog-Upload-Command |
מגדירים את הערך start. |
X-Goog-Upload-Content-Type |
מגדירים את סוג ה-MIME של הקובץ, לדוגמה,
image/jpeg. |
X-Goog-Upload-Protocol |
מגדירים את הערך resumable. |
X-Goog-Upload-Raw-Size |
צריך להגדיר את המספר הכולל של הבייטים של נתוני הקובץ להעברה. |
זו כותרת של בקשת POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
שלב 2: שמירת כתובת ה-URL של הסשן
אם הבקשה תתבצע בהצלחה, בקשת ה-POST תחזיר קוד סטטוס HTTP 200 OK, כולל הכותרת הבאה.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
שדה הכותרת x-goog-upload-chunk-granularity מכיל את רמת הפירוט של הגודל ואת היישור של הבייטים לכל קטעי הנתונים שנשלחים על ידי הלקוח. אם ההעלאה מתבצעת במספר קטעים, כל ההעלאות, מלבד ההעלאה האחרונה, צריכות להתבצע בערכים שהם כפולות של הערך הזה. כלומר, הבייטים של העלאת הקובץ חייבים להיות מותאמים לערך הזה. בחלק האחרון תוכלו להעלות את הבייטים הנותרים.
שדה הכותרת X-Goog-Upload-URL מכיל כתובת URL ייחודית שצריך להשתמש בה כדי להשלים את ההעלאה באמצעות כל הבקשות שנותרו. מעתיקים ושומרים את כתובת ה-URL של הסשן שניתן להמשיך, כדי שתוכלו להשתמש בה בבקשות הבאות.
שלב 3: העלאת הקובץ
יש שתי דרכים להעלות קובץ באמצעות סשן שניתן להמשיך:
- בבקשה אחת. בדרך כלל הגישה הזו היא הטובה ביותר, כי היא דורשת פחות בקשות, ולכן הביצועים שלה טובים יותר.
-
במספר מקטעים. בגישה הזו, ההעלאות מתבצעות במספר בקשות על ידי חלוקת הנתונים למקטעים. הנתונים מחולקים למקטעים בכפולות של
x-goog-upload-chunk-granularity. במקרה הצורך, אפשר לנסות שוב את הבקשות המחולקות.כדאי להשתמש בגישה הזו אם:
- צריך להפחית את כמות הנתונים שמועברת בבקשה אחת. יכול להיות שתצטרכו לעשות זאת אם יש מגבלה זמן קבועה לבקשות ספציפיות.
- עליך לספק אינדיקטור מותאם אישית שמראה את התקדמות ההעלאה.
- חשוב לדעת מתי אפשר להשמיד נתונים בבטחה.
בקשה יחידה
כדי להעלות את הקובץ בבקשה אחת:
- יוצרים בקשה מסוג
POSTלכתובת ה-URL של הסשן שניתן להמשיך. - מוסיפים את נתוני הקובץ לגוף הבקשה.
מוסיפים את כותרות ה-HTTP הבאות:
Content-Length: מוגדר למספר הבייטים בקובץ.X-Goog-Upload-Command: מוגדר ל-upload, finalize.
שולחים את הבקשה.
אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג 5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.
אם הבקשה תתבצע בהצלחה, תקבלו קוד סטטוס HTTP
200 OK ואסימון העלאה בגוף התשובה.
יוצרים את פריט המדיה באמצעות אסימון ההעלאה הזה.
גושים מרובים
כדי להעלות את הקובץ במספר מקטעים:
- יוצרים בקשה מסוג
POSTלכתובת ה-URL של הסשן שניתן להמשיך. -
מוסיפים את נתוני הקטע לגוף הבקשה.
חוץ מהקטע האחרון שמסתיים בהעלאה, צריך ליצור את שאר הקטעים ככפולות של גודל הקטעים המקובל. מומלץ להגדיר את גודל הקטעים כמה שיותר גדול כדי שההעלאה תהיה יעילה.
-
מוסיפים את כותרות ה-HTTP הבאות:
Content-Length: מוגדר למספר הבייטים בקטע.X-Goog-Upload-Command: מוגדר לערךupload. למקטע האחרון, מגדירים את הערךupload, finalize.X-Goog-Upload-Offset: מוגדר לפער שבו צריך לכתוב את הבייטים. חשוב לזכור שצריך להעלות את הבייטים בסדר. ההיסט הראשון הוא0.
- שולחים את הבקשה.
אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג
5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה. - חוזרים על השלבים האלה לכל מקטע שנותר בקובץ.
אם הבקשה תאושר, תקבלו קוד סטטוס HTTP 200 OK ואסימון העלאה בגוף התגובה.
יוצרים את פריט המדיה באמצעות אסימון ההעלאה הזה.
דוגמה
בקשה יחידה
בדוגמה הבאה מוצגת בקשה שניתן להמשיך, כדי להעלות קובץ JPEG בגודל 3,039,417 בייטים בבקשה אחת.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
התשובה מכילה את כתובת ה-URL להעלאה ואת גודל הקטע הצפוי:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
בקשת ההעלאה הסופית:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
מספר גושים
בדוגמה הבאה מוצגת בקשה שניתן להמשיך אותה להעלאת קובץ JPEG בנפח 3,039,417 בייטים בכמה קטעים, באמצעות כתובת ה-URL של הסשן שניתן להמשיך אותו ורמת הפירוט של גודל הקטעים שהתקבלה בשלב הקודם.
בדוגמה הזו נעשה שימוש בגודל מקטע של 262,144 בייטים שהוחזרו בשדה הכותרת, x-goog-upload-chunk-granularity, כשסשן ההעלאה התחיל. חשוב לזכור שכל העלאה מכילה בייטים שמספרם הוא מכפיל של 262,144.
מפעילים את סשן ההעלאה כדי לקבל את כתובת ה-URL להעלאה ואת גודל הקטעים, כפי שמתואר בשלב הקודם:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
התשובה מכילה את כתובת ה-URL להעלאה ואת גודל הקטע הצפוי:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
מקטע ראשון:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
מקטע שני:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
מקטע אחרון:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
המשך העלאה שהופסקה
אם בקשת ההעלאה הופסקה או אם מקבלים קוד סטטוס HTTP שאינו 200, שולחים שאילתות לשרת כדי לבדוק כמה מההעלאה בוצעה.
זוהי בקשה POST לכתובת ה-URL של הסשן שניתן להמשיך. צריך להגדיר את X-Goog-Upload-Command לערך query.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
התגובה מהשרת כוללת את קוד הסטטוס 200 OK של HTTP ואת הגודל הנוכחי של ההעלאה.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
לאחר מכן תוכלו להמשיך בהעלאה מהמקום שבו הפסקתם. צריך להמשיך מההיסט שסופק על ידי השרת, אלא אם שולחים פקודה משולבת של העלאה וסיום, ובמקרה כזה אפשר להמשיך גם מההיסט 0.
אם הכותרת X-Goog-Upload-Status מופיעה בתגובת ה-HTTP של פקודת השאילתה והערך שלה הוא לא active, סימן שההעלאה כבר הסתיימה.