支援續傳的上傳作業

設定方式

本頁面說明 Cloud Storage 中支援續傳的上傳作業。建議您使用支援續傳的上傳作業來上傳大型檔案，因為如果上傳期間發生網路故障，您不必從頭重新上傳。

簡介

如因通訊問題導致資料傳輸過程遭到中斷，之後可透過可續傳的上傳作業繼續執行資料傳輸作業，將資料傳輸至 Cloud Storage。支援續傳的上傳作業會傳送多個要求，每個要求都包含您要上傳的部分物件。這與單一要求上傳不同，後者在單一要求中包含物件的所有資料，如果中途失敗，就必須從頭開始。

支援續傳的上傳作業會透過支援續傳的上傳工作階段運作。當您啟動上傳作業時，Cloud Storage 會建立工作階段，並傳回專屬的工作階段 URI。您或委派的用戶端 (例如網路瀏覽器) 隨後會透過一或多個要求，將物件資料傳送至這個工作階段 URI。每個工作階段最多可維持一週，因此如果上傳作業因網路中斷或用戶端重新啟動而中斷，可以繼續上傳。

  • 如果您要上傳大型檔案，或透過緩慢的連線上傳，請使用支援續傳的上傳作業。如需使用支援續傳的上傳作業時的檔案大小限制範例，請參閱「上傳大小注意事項」。

  • 支援續傳的上傳作業必須在啟動後一週內完成，但隨時可以取消。

  • 只有完成的支援續傳的上傳作業會顯示在值區中，並在適用情況下取代現有同名物件。

  • 完成支援續傳的上傳作業，即視為一次 A 類作業。

工具和 API 如何使用支援續傳的上傳作業

視您與 Cloud Storage 的互動方式而定，系統可能會自動為您管理支援續傳的上傳作業。本節說明不同工具的支援續傳的上傳作業行為，並提供指引，協助您為應用程式設定適當的緩衝區空間。

控制台

Google Cloud 控制台會自動代您管理支援續傳的上傳作業。不過，如果您在上傳期間重新整理或離開Google Cloud 控制台，上傳作業就會取消。

指令列

將資料上傳至 Cloud Storage 時，gcloud CLI 會在 gcloud storage cp 和 gcloud storage rsync 指令中使用支援續傳的上傳作業。如果上傳作業中斷，您可以執行與啟動上傳作業時相同的指令，繼續上傳。如要繼續上傳這類包含多個檔案的項目，請使用 --no-clobber 旗標，避免重新上傳已成功完成的檔案。

用戶端程式庫

執行支援續傳的上傳作業時，用戶端程式庫會做為 Cloud Storage JSON API 的包裝函式。

C++

storage::Client 中的函式會以不同行為執行：

根據預設，如果物件大於 20 MiB，UploadFile() 會執行支援續傳的上傳作業。否則，系統會執行簡單上傳或多部分上傳。建立 storage::Client 時，您可以設定 MaximumSimpleUploadsSizeOption 來設定這項門檻。

預設緩衝區大小為 8 MiB，您可以使用 UploadBufferSizeOption 選項修改。

C++ 用戶端程式庫使用的緩衝區空間等於區塊大小。緩衝區空間必須是 256 KiB (256 x 1024 位元組) 的倍數。使用 WriteObject() 和 UploadFile() 時，建議您考量上傳速度和記憶體用量之間的取捨。使用小型緩衝區上傳大型物件可能會導致上傳速度變慢。如要進一步瞭解 C++ 的上傳速度和緩衝區空間之間的關係，請參閱 GitHub 中的詳細分析。

C#

上傳時，C# 用戶端程式庫一律會執行支援續傳的上傳作業。你可以使用 CreateObjectUploader 啟動支援續傳的上傳作業。

C# 用戶端程式庫使用的緩衝區空間等於區塊大小。預設緩衝區空間為 10 MB，您可以在 UploadObjectOptions 上設定 ChunkSize 來變更這個值。緩衝區大小必須是 256 KiB (256 x 1024 位元組) 的倍數。緩衝區空間越大，上傳速度通常越快，但請注意，速度和記憶體用量之間會相互制衡。

Go

根據預設，如果檔案大於 16 MiB，系統會自動執行支援續傳的上傳作業。您可以使用 Writer.ChunkSize 變更執行可續傳上傳作業的截止時間。使用 Go 用戶端程式庫時，支援續傳的上傳作業一律會分塊。

如果物件小於 Writer.ChunkSize，或 Writer.ChunkSize 設為 0 (停用分塊)，就會進行多部分上傳。如果 ChunkSize 設為 0，Writer 就無法重試要求。

Go 用戶端程式庫使用的緩衝區空間等於區塊大小。緩衝區大小必須是 256 KiB (256 x 1024 位元組) 的倍數。緩衝區空間越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要取捨。如果同時執行多個支援續傳的上傳作業，請將 Writer.ChunkSize 設為小於 16 MiB 的值，以免記憶體膨脹。

請注意，在您呼叫 Writer.Close() 並收到成功回應之前，物件不會在 Cloud Storage 中完成。如果要求失敗，Writer.Close 會傳回錯誤。

Java

Java 用戶端程式庫提供個別方法，用於多部分和支援續傳的上傳作業。下列方法一律會執行支援續傳的上傳作業：

預設緩衝區空間為 15 MiB。您可以透過 WriteChannel#setChunkSize(int) 方法設定緩衝區空間，或將 bufferSize 參數傳遞至 Storage#createFrom 方法。緩衝區空間大小下限為 256 KiB。在內部呼叫 WriteChannel#setChunkSize(int) 時，緩衝區空間會移至 256 KiB 的倍數。

支援續傳的上傳作業緩衝區會做為清除門檻下限，小於緩衝區空間的寫入作業會緩衝處理，直到寫入作業將緩衝處理的位元組數推至緩衝區空間以上。

如要上傳少量資料，請考慮使用 Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) 或 Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...)。

Node.js

系統會自動執行支援續傳的上傳作業。如要關閉支援續傳的上傳作業，請將 UploadOptions 的 resumable 設為 false。使用 createWriteStream 方法時，系統會自動管理支援續傳的上傳作業。

系統沒有預設緩衝區空間，您必須在 CreateResumableUploadOptions 上設定 chunkSize 選項，手動叫用分塊上傳。如果指定 chunkSize，系統會以個別的 HTTP 要求傳送資料，每個要求的酬載大小為 chunkSize。如果未指定 chunkSize，且程式庫正在執行支援續傳的上傳作業，所有資料都會串流至單一 HTTP 要求。

Node.js 用戶端程式庫使用的緩衝區空間等於區塊大小。緩衝區空間必須是 256 KiB (256 x 1024 位元組) 的倍數。緩衝區空間越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要權衡。

PHP

根據預設，當物件大小超過 5 MB 時，系統會自動進行支援續傳的上傳作業。否則會進行多部分上傳。這個門檻無法變更。您可以在 upload 函式中設定 resumable 選項，強制執行支援續傳的上傳作業。

PHP 用戶端程式庫使用的緩衝區空間等於區塊大小。256KiB 是支援續傳的上傳作業的預設緩衝區空間，您可以設定 chunkSize 屬性來變更緩衝區空間。緩衝區大小必須是 256 KiB (256 x 1024 位元組) 的倍數。緩衝區空間越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要取捨。

Python

如果物件大於 8 MiB，系統會執行支援續傳的上傳作業；如果物件小於 8 MiB，則會執行多部分上傳作業。這個門檻無法變更。Python 用戶端程式庫使用的緩衝區空間等於區塊大小。100 MiB 是支援續傳的上傳作業所用的預設緩衝區空間，您可以設定 blob.chunk_size 屬性來變更緩衝區空間。

如要一律執行支援續傳的上傳作業，無論物件大小為何，請使用 storage.BlobWriter 類別或 storage.Blob.open(mode='w') 方法。這些方法的預設緩衝區空間為 40 MiB。你也可以使用「支援續傳的媒體」管理支援續傳的上傳作業。

區塊大小必須是 256 KiB (256 x 1024 位元組) 的倍數。區塊越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要權衡。

小茹

Ruby 用戶端程式庫會將所有上傳作業視為非分塊的可續傳上傳作業。

REST API

JSON API

Cloud Storage JSON API 會使用包含查詢參數 uploadType=resumable 的 POST Object 要求，啟動支援續傳的上傳作業。這項要求會傳回工作階段 URI，您隨後會在一個或多個 PUT Object 要求中使用這個 URI，上傳物件資料。如需建構支援續傳的上傳作業邏輯的逐步指南，請參閱「執行支援續傳的上傳作業」。

XML API

Cloud Storage XML API 會使用包含 x-goog-resumable: start 標頭的 POST Object 要求，啟動支援續傳的上傳作業。這項要求會傳回「工作階段 URI」，您隨後可在一或多個 PUT Object 要求中使用該 URI 上傳物件資料。如需建構支援續傳的上傳作業邏輯的逐步指南，請參閱「執行支援續傳的上傳作業」。

如果跨源用戶端 (例如網路瀏覽器) 會上傳資料，請在建立工作階段的初始要求中加入用戶端的 Origin 標頭。Cloud Storage 會根據初始要求決定 CORS 標頭。如果在工作階段啟動期間省略 Origin，Cloud Storage 就不會在後續上傳要求的回應中加入 CORS 標頭，導致瀏覽器跨源要求失敗。

支援續傳的上傳作業 (大小不明)

可續傳上傳機制支援檔案大小不明的移轉作業。這項功能適用於上傳時即時壓縮物件等情況，因為在傳輸開始時，很難預測壓縮檔案的確切大小。如果您想串流傳輸可於中斷後繼續的資料，或是區塊轉移編碼不適用於您的應用程式，這個機制就很有用。

詳情請參閱「串流上傳」。

上傳效能

選擇工作階段區域

支援續傳的上傳作業會固定在啟動作業的區域。舉例來說，如果您在美國啟動支援續傳的上傳作業，並將工作階段 URI 提供給亞洲的用戶端，上傳作業仍會透過美國進行。為減少跨區域流量並提升效能，請將支援續傳的上傳作業保留在建立時所在的區域。

如果您使用 Compute Engine 執行個體啟動支援續傳的上傳作業，該執行個體應與您要上傳的 Cloud Storage bucket 位於相同位置。接著，您可以使用地理 IP 服務，選擇要將客戶要求轉送至哪個 Compute Engine 區域，這有助於將流量限制在特定地理區域。

分塊上傳

請盡可能避免將傳輸作業拆成較小的區塊，而是將整個內容上傳為單一區塊。避免分塊可消除查詢每個分塊的持續偏移量時，產生的額外延遲時間成本和作業費用，並提高處理量。不過，在下列情況下，建議您分塊上傳：

  • 來源資料是動態產生，您希望限制用戶端緩衝處理的資料量，以免上傳失敗。

  • 用戶端有要求大小限制，許多瀏覽器也是如此。

如果您使用的是 JSON 或 XML API，且用戶端收到錯誤，則可向伺服器查詢持續性偏移量，並從該偏移量繼續上傳剩餘位元組。 Google Cloud 控制台、Google Cloud CLI 和用戶端程式庫會自動為您處理這項作業。如要進一步瞭解如何為特定用戶端程式庫進行分塊，請參閱「工具和 API 如何使用支援續傳的上傳作業」。

注意事項

如果您要建構自己的用戶端，直接將支援續傳的上傳作業要求傳送至 JSON 或 XML API，這個章節會很有幫助。

工作階段 URI

當您啟動支援續傳的上傳作業時，Cloud Storage 會傳回工作階段 URI，您可以在後續要求中使用這個 URI 上傳實際資料。JSON API 中的工作階段 URI 範例如下：

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

XML API 中的工作階段 URI 範例如下：

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

這個工作階段 URI 會做為驗證權杖，因此使用該 URI 的要求不需要簽署，任何人都能使用該 URI 將資料上傳至目標值區，無須進一步驗證。因此，請謹慎共用工作階段 URI，並僅透過 HTTPS 共用。

工作階段 URI 會在一週後失效，但可在失效前取消。如果您使用已失效的工作階段 URI 提出要求，會收到下列其中一項錯誤：

  • 如果上傳作業啟動後不到一週，則會傳回 410 Gone 狀態碼。
  • 如果上傳作業已啟動超過一週，則為 404 Not Found 狀態碼。

在這兩種情況下，或是在上傳完成前遺失工作階段 URI 時，您都必須啟動新的支援續傳的上傳作業、取得新的工作階段 URI，然後使用新的工作階段 URI 從頭開始上傳。

完整性檢查

建議您要求對最終上傳的物件進行完整性檢查，確保物件與來源檔案相符。方法是計算來源檔案的 MD5 摘要，然後將其新增至 Content-MD5 要求標頭。

如果您要上傳大型檔案，且上傳時間較長，請務必檢查上傳檔案的完整性，因為上傳作業進行期間，來源檔案修改的可能性會增加。

不過，您無法對支援續傳的上傳作業的中間部分或區塊執行完整性檢查，因為支援續傳的上傳作業的目的是讓您在上傳作業意外中斷時，可以繼續上傳。

重試和重新傳送資料

Cloud Storage 在支援續傳的上傳作業中保留位元組後，就無法覆寫這些位元組，Cloud Storage 也會忽略覆寫嘗試。因此，倒轉至先前傳送的偏移量時，請勿傳送不同的資料。

舉例來說，假設您要上傳 100,000 位元組的物件，但連線中斷。檢查狀態時，您會發現 50,000 個位元組已成功上傳並保存。如果您嘗試在第 40,000 個位元組重新啟動上傳作業，Cloud Storage 會忽略您從第 40,000 個位元組傳送至第 50,000 個位元組的位元組。Cloud Storage 會從第 50,001 個位元組開始保存您傳送的資料。

後續步驟