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

בדף הזה מוסבר איך שולחים בקשת העלאה שניתן להמשיך אל 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 מחזירה את קוד הסטטוס 200 OK של HTTP, כולל הכותרת הבאה.

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

התגובה מהשרת כוללת את קוד הסטטוס 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, המשמעות היא שההעלאה כבר הסתיימה.