執行支援續傳的上傳作業

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

複製並儲存支援續傳的重新執行網址，方便您在後續要求中使用。

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

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

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 的倍數 (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 狀態碼。

多個區塊

以下範例顯示一個續傳要求，將 4,200,000 位元組的 JPEG 檔案分成多個區塊，並使用可續傳工作階段網址和您在上一個步驟中取得的大小精細程度。本範例使用 2097, 000 位元組的區塊大小，這是 2 MiB (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，則代表上傳作業已經終止。