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

בדף זה מוסבר איך ליצור בקשת העלאה שניתנת לחידוש דרך Street ViewPublish 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 (mebibytes), מלבד המקטע האחרון שמשלים את ההעלאה. מומלץ להגדיל ככל האפשר את גודל המקטעים כדי שההעלאה תתבצע ביעילות.

  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]

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

גושים מרובים

הדוגמה הבאה מציגה בקשה שניתן להמשיך ולהעלות קובץ JPEG בגודל 4,200,000 בייטים במספר מקטעים, תוך שימוש בכתובת ה-URL של הסשן שניתנת לחידוש וברמת פירוט הגודל שהושגה בשלב הקודם. בדוגמה הזו נעשה שימוש בגודל קבוצת נתונים של 2097,000 בייטים, שהיא כפולה של 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, ההעלאה כבר הסתיימה.