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

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

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

  • 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 של הסשן לטעינה מחדש ורמת הפירוט של הגודל שהתקבלו בשלב הקודם. בדוגמה הזו נעשה שימוש בגודל מקטע של 2097000 בייטים, שהוא כפולה של 2MiB (מבי-בייט).

הקטע הראשון: 

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, סימן שההעלאה כבר הסתיימה.