支援續傳的上傳作業

設定方式

本頁討論 Cloud Storage 中的可續傳上傳作業。建議使用斷點續傳方式上傳大文件，因為如果在上傳過程中發生網路故障，您不必從頭開始重新上傳。

簡介

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

支援續傳的上傳作業會透過支援續傳的上傳工作階段運作。當您發起上傳時，Cloud Storage 會建立一個會話並傳回一個唯一的會話 URI。然後，您或受委託的用戶端（例如 Web 瀏覽器）會將物件資料透過一個或多個請求傳送至此會話 URI。每個工作階段最多可維持一週，因此如果上傳作業因網路中斷或用戶端重新啟動而中斷，可以繼續上傳。

  • 如果上傳大型檔案或透過連線速度緩慢的網路上傳檔案，請使用支援續傳的上傳作業。例如，關於使用可恢復上傳的檔案大小限制，請參閱上傳大小注意事項。

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

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

    • 物件的建立時間是以上傳完成時間為準。

    • 使用者設定的物件元資料在初始請求中指定。 上傳完成後，系統就會將這項中繼資料套用至物件。

    • 如果您在最終要求中加入以 X-Goog-Meta- 為前置字元標頭，JSON API 也支援在最終要求中設定自訂中繼資料。

  • 一次完成的支援續傳的上傳作業被視為一次 A 類別操作。

工具和 API 如何使用斷點續傳上傳

根據您與雲端儲存的互動方式，可恢復上傳可能會自動為您管理。本節介紹不同工具的支援續傳的上傳作業行為，並指導您如何為應用程式配置適當的緩衝區空間。

控制台

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

指令列

gcloud CLI 在 gcloud storage cp 和 gcloud storage rsync 指令中上傳資料到 Cloud Storage 時使用可恢復上傳。如果上傳作業中斷，可以執行啟動上傳作業時使用的相同指令，繼續上傳。如要繼續上傳這類包含多個檔案的項目，請使用 --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 值區位於相同位置。然後，您可以使用地理 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 時要謹慎，並且只能透過 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 傳送的位元組。雲端儲存從第 50,001 位元組開始持久化您發送的資料。

後續步驟