ביצוע העלאה ניתנת לחידוש

בדף הזה מוסבר איך ליצור בקשת העלאה שניתן להמשיך ב-Street View Publish API. הפרוטוקול הזה מאפשר להמשיך את פעולת ההעלאה אחרי שכשל בתקשורת מפריע לזרימת הנתונים. כדאי להשתמש באפשרות הזו אם:

  • אתם מעלים קבצים גדולים.
  • הסיכוי להפרעה ברשת או לכשל אחר בהעברה גבוה (לדוגמה, אם מעלים קובץ מאפליקציה לנייד).

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

אם אתם שולחים קבצים קטנים באמצעות חיבור רשת אמין, אתם יכולים להשתמש בהעלאה פשוטה במקום זאת.

התחלת סשן העלאה שניתן להמשיך

אחרי שמקבלים uploadUrl, אפשר להתחיל סשן העלאה שניתן להמשיך:

  1. יוצרים בקשת POST אל uploadUrl.

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

    • ‫X-Goog-Upload-Protocol: מוגדר ל-resumable.
    • ‫X-Goog-Upload-Header-Content-Length: הערך שמוגדר הוא המספר הכולל של בייטים של נתוני הקובץ, שיועברו בבקשות הבאות.
    • ‫X-Goog-Upload-Header-Content-Type: הערך שמוגדר כאן הוא סוג ה-MIME של נתוני הקובץ.
    • ‫X-Goog-Upload-Command: מוגדר ל-start.

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

דוגמה: הפעלת סשן העלאה שניתן להמשיך

בדוגמה הבאה אפשר לראות איך מתחילים סשן העלאה שניתן להמשיך כדי להעלות קובץ חדש. במקרה הזה, הקובץ הוא תמונה והמספר הכולל של הבייטים בקובץ הוא 4200000. שימו לב שגוף הבקשה ריק, ולכן הכותרת Content-Length מוגדרת ל-0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

במאמר שמירת כתובת ה-URL של הסשן שניתן להמשיך מוסבר איך לטפל בתגובה לבקשה להתחלת סשן העלאה שניתן להמשיך.

שמירת כתובת ה-URL של הסשן שניתן להמשיך

לגבי הבקשה שנשלחה כדי להתחיל סשן העלאה שניתן להמשיך, השרת ישיב עם קוד סטטוס של 200 OK HTTP, כולל הכותרת הבאה:

  • ‫X-Goog-Upload-URL: כתובת URL ייחודית שחובה להשתמש בה כדי להשלים את ההעלאה בכל הבקשות שנותרו.

מעתיקים ושומרים את כתובת ה-URL של הסשן שניתן להמשך, כדי שתוכלו להשתמש בה בבקשות הבאות.

דוגמה: שמירת כתובת ה-URL של הסשן שניתן להמשיך

בדוגמה הבאה מוצגת תגובה שכוללת כתובת URL של סשן שאפשר להמשיך אותו ודרישה לגרנולריות של גודל.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

העלאת הקובץ

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

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

בקשה יחידה

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

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

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

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

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

אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג 5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.

כמה גושים

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

  1. יוצרים בקשת POST לכתובת ה-URL של הסשן שניתן להמשיך.
  2. מוסיפים את נתוני החלק לגוף הבקשה. יוצרים מקטעים בכפולות של 2MiB (מביבייט), למעט המקטע האחרון שמשלים את ההעלאה. כדאי להגדיל את גודל המקטע ככל האפשר כדי שההעלאה תהיה יעילה.

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

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

  4. שולחים את הבקשה. אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג 5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.

  5. חוזרים על שלבים 1 עד 4 לכל נתח שנותר בקובץ.

דוגמה: העלאת הקובץ

בקשה יחידה

בדוגמה הבאה מוצגת בקשה להעלאה שניתן להמשיך, של קובץ JPEG בגודל 4,200,000 בייט בבקשה אחת, באמצעות כתובת ה-URL של הסשן שניתן להמשיך שהתקבלה בשלב הקודם:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

אם הבקשה תתבצע בהצלחה, תקבלו קוד סטטוס 200 OK של HTTP.

כמה גושים

בדוגמה הבאה מוצגת בקשה להעלאה של קובץ JPEG בגודל 4,200,000 בייט בכמה מקטעים, באמצעות כתובת ה-URL של הסשן שניתן להמשיך אותו וגודל הגרנולריות שהתקבל בשלב הקודם. בדוגמה הזו, גודל המקטע הוא 2,097,000 בייטים, שהם כפולה של 2 מיביבייט (MiB).

החלק הראשון: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

חלק שני: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

החלק האחרון: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

המשך העלאה שהופסקה

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

  1. יוצרים בקשת POST לכתובת ה-URL של הסשן שניתן להמשיך.
  2. מגדירים את X-Goog-Upload-Command לערך query.
  3. שולחים את הבקשה.

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