執行支援續傳的上傳作業

本頁說明如何在 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：必須透過所有剩餘要求使用這個專屬網址，才能完成上傳作業。

請複製並儲存可續傳的 Ression URI，以便在後續要求中使用。

範例：儲存可續傳的工作階段網址

以下範例顯示回應，其中包含可續傳的工作階段網址和大小精細度要求。

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 (mebibytes) 的倍數，但會完成上傳作業的最後一個區塊除外。請盡可能將區塊大小設為較大，以便提高上傳效率。

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

多個區塊

以下範例顯示使用可續傳工作階段網址，以及上一個步驟中取得的大小精細程度，在多個區塊中上傳 4,200,000 位元組的 JPEG 檔案可續傳要求。這個範例使用的區塊大小為 2097000 位元組，是 2 MiB (mebibytes) 的倍數。

第一個區塊：

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，則表示上傳作業已終止。