העלאות שניתן להמשיך

בדף הזה מוסבר איך ליצור בקשת העלאה שניתן להמשיך ל-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: העלאת הקובץ

יש שתי דרכים להעלות קובץ באמצעות סשן שניתן להמשיך:

  1. בבקשה אחת. בדרך כלל הגישה הזו היא הטובה ביותר, כי הוא דורש פחות בקשות, ולכן הביצועים שלו טובים יותר.

  2. במספר מקטעים. בשיטה הזו, מתבצעות העלאות בבקשות מרובות על ידי קיבוץ הנתונים. הנתונים מפולחים לפי כפולות של x-goog-upload-chunk-granularity. במקרה הצורך, אפשר לנסות שוב את הבקשות במקטעים.

    כדאי להשתמש בגישה הזו אם:

    • צריך להפחית את כמות הנתונים שמועברים בכל בקשה. יכול להיות שתצטרכו לעשות זאת כשיש מגבלת זמן קבועה עבור לבקשות נפרדות.
    • צריך לספק אינדיקטור מותאם אישית שמראה את ההעלאה על ההתקדמות במשחק.
    • עליכם לדעת מתי אפשר למחוק נתונים בבטחה.

בקשה יחידה

כדי להעלות את הקובץ בבקשה אחת:

  1. יוצרים בקשת POST לכתובת ה-URL של הסשן שניתן להמשיך.
  2. מוסיפים את נתוני הקובץ לגוף הבקשה.

  3. מוסיפים את כותרות ה-HTTP הבאות:

    • Content-Length: מוגדר למספר הבייטים בקובץ ה- חדש.
    • X-Goog-Upload-Command: מוגדר ל-upload, finalize.

  4. שולחים את הבקשה.

אם בקשת ההעלאה נקטעת או אם מקבלים 5xx יש לבצע את התהליך שבקטע המשך של ההעלאה הופסקה.

אם הבקשה תתבצע בהצלחה, תקבלו סטטוס HTTP 200 OK ואסימון העלאה בגוף התגובה. יצירה פריט המדיה באמצעות אסימון ההעלאה הזה.

גושים מרובים

כדי להעלות את הקובץ במספר מקטעים:

  1. יוצרים בקשה מסוג POST לכתובת ה-URL של הסשן שניתן להמשיך.

  2. מוסיפים את נתוני המקטע לגוף הבקשה.

    מלבד המקטע הסופי שמבצע את ההעלאה, יוצרים את המקטע מקטעים אחרים בכפולות של גודל המקטעים המקובל. יש להשאיר את גודל מקטע גדול ככל האפשר כדי שההעלאה תהיה יעילה.

  3. מוסיפים את כותרות ה-HTTP הבאות:

    • Content-Length: מוגדר למספר הבייטים בקובץ ה- של מקטע הנתונים.
    • X-Goog-Upload-Command: מוגדר ל-upload. למקטע האחרון, מגדירים את הערך upload, finalize.
    • X-Goog-Upload-Offset: מוגדר לקיזוז שבו צריך לכתוב בייטים. חשוב לזכור שצריך להעלות את הבייטים בסדר. ההיסט הראשון הוא 0.
  4. שולחים את הבקשה.

    אם בקשת ההעלאה נקטעת או אם מקבלים 5xx יש לבצע את התהליך שבקטע המשך של ההעלאה הופסקה.

  5. חוזרים על השלבים האלה לכל מקטע שנותר בקובץ.

אם הבקשה תתבצע בהצלחה, תקבלו סטטוס 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, שמציין שההעלאה כבר הופסק.