執行支援續傳的上傳作業

本頁說明如何在 Street View Publish API 中提出可續傳的上傳要求。如因通訊問題導致資料傳輸過程遭到中斷，之後可透過此通訊協定繼續執行上傳作業。如果符合以下描述，請使用這個選項：

  • 上傳大型檔案。
  • 網路中斷或其他傳輸失敗的可能性很高 (例如從行動應用程式上傳檔案時)。

發生網路問題時，可續傳上傳作業也能減少頻寬用量，因為您不需要從頭開始上傳大型檔案。

如果透過穩定的網路連線傳送小型檔案，可以使用簡單的上傳方式。

啟動支援續傳的上傳工作階段

取得 uploadUrl 後，即可啟動可續傳的上傳工作階段：

  1. 對 uploadUrl 建立 POST 要求。

  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

儲存可續傳工作階段網址一節說明如何處理啟動可續傳上傳工作階段的要求回應。

儲存續傳工作階段網址

伺服器會針對啟動可繼續上傳工作階段的要求，回覆 200 OK HTTP 狀態碼，包括下列標頭：

  • X-Goog-Upload-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 要求。
  2. 將檔案資料新增到要求主體。

  3. 新增下列 HTTP 標頭：

    • Content-Length：設為檔案中的位元組數。
    • X-Goog-Upload-Command：設為 upload, finalize。

  4. 傳送要求。

如果上傳要求中斷，或是收到 5xx 回應，請按照「繼續執行中斷的上傳作業」一節所述的程序進行。

多個區塊

如要分塊上傳檔案，請按照下列步驟操作：

  1. 對可續傳工作階段網址建立 POST 要求。
  2. 將區塊的資料新增至要求主體。建立的區塊大小必須是 2 MiB (兆位元組) 的倍數，但會完成上傳作業的最後一個區塊除外。請盡量將區塊設為較大，以保持上傳效率。

  3. 新增下列 HTTP 標頭：

    • Content-Length：設為區塊中的位元組數。
    • X-Goog-Upload-Command：設為 upload。最後一個區塊請設為 upload, finalize。
    • X-Goog-Upload-Offset：設為應寫入位元組的位移。請注意，位元組必須依序上傳。

  4. 傳送要求。如果上傳要求中斷，或是收到 5xx 回應，請按照「繼續執行中斷的上傳作業」一節所述的程序進行。

  5. 針對檔案中的每個剩餘區塊，重複執行步驟 1 到 4。

範例：上傳檔案

單一要求

以下範例顯示續傳要求，可使用上一個步驟中取得的續傳工作階段網址，在單一要求中上傳整個 4,200,000 位元組的 JPEG 檔案：

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 狀態碼。

多個區塊

以下範例顯示如何使用可續傳的工作階段 URL 和上一個步驟取得的大小精細度，以多個區塊上傳 4,200,000 位元組的 JPEG 檔案。這個範例使用的區塊大小為 2097000 個位元組，是 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]

繼續執行中斷的上傳作業

如果上傳要求中斷，或是您收到非 200 的 HTTP 狀態碼，請查詢伺服器，瞭解上傳作業的成功程度：

  1. 對可續傳工作階段網址建立 POST 要求。
  2. 將 X-Goog-Upload-Command 設為 query。
  3. 傳送要求。

伺服器會傳回 200 OK HTTP 狀態碼，以及目前上傳的大小：

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

然後從這個偏移量繼續上傳。除非您傳送合併上傳和完成指令，否則必須從伺服器提供的位移量繼續上傳，在這種情況下，您也可以從位移量 0 繼續上傳。

如果查詢指令的 HTTP 回應中存在 X-Goog-Upload-Status 標頭，且值不是 active，則上傳作業已終止。