בדף הזה מוסבר איך ליצור בקשת העלאה שניתן להמשיך ל-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
התגובה מהשרת כוללת קוד מצב HTTP 200 OK
ואת
הגודל הנוכחי של ההעלאה.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
לאחר מכן תוכלו להמשיך את ההעלאה בקיזוז הזה. צריך להמשיך את המשחק לאחר הקיזוז שסופקו על ידי השרת, אלא אם תשלחו פקודת העלאה משולבת ומסיימים, במקרה כזה אפשר להמשיך גם בהיסט 0.
אם הכותרת X-Goog-Upload-Status
בתגובת ה-HTTP של פקודת השאילתה
קיים והערך אינו active
, שמציין שההעלאה
כבר הופסק.