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

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

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

דוגמה: שמירת כתובת ה-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]

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