支援續傳的上傳作業

設定方式

本頁討論 Cloud Storage 中的可續傳上傳作業。建議使用可續傳上傳功能上傳大型檔案,因為上傳期間如果發生網路問題,您不需要從頭開始上傳。

簡介

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

  • 如果上傳大型檔案或透過連線速度緩慢的網路上傳檔案,請使用支援續傳的機制。如需使用支援續傳的上傳作業時的檔案大小截斷範例,請參閱上傳大小注意事項

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

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

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

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

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

  • 完成可續傳的上傳作業會視為一項 A 級作業

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

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

控制台

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

指令列

使用 gcloud CLI 將資料上傳至 Cloud Storage 時,gcloud storage cpgcloud 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.ChunkSizeWriter.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 用戶端程式庫使用的緩衝區大小等於區塊大小。256 KiB 是可繼續上傳的預設緩衝區大小,您可以設定 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。您也可以使用 Resumable Media 管理支援續傳的上傳作業。

區塊大小必須是 256 KiB (256 x 1024 位元組) 的倍數。通常來說,區塊越大,上傳速度就越快,但請注意,速度和記憶體用量之間會有所取捨。

Ruby

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

REST API

JSON API

Cloud Storage JSON API 會使用包含查詢參數 uploadType=resumablePOST Object 要求,啟動可續傳的上傳作業。這項要求會傳回工作階段 URI,您接著會在一個或多個 PUT Object 要求中使用該 URI,上傳物件資料。如需逐步指南,瞭解如何建構自己的續傳上傳邏輯,請參閱「執行續傳上傳作業」。

XML API

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

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

可恢復上傳機制支援檔案大小不明的傳輸作業。這在某些情況下非常實用,例如在上傳時即時壓縮物件,因為在傳輸開始時,很難預測壓縮檔案的確切大小。如果您想串流傳輸可於中斷後繼續的資料,或區塊傳輸編碼不適用於您的應用程式,這個機制就非常實用。

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

上傳效能

選擇會話區域

支援續傳的上傳作業最好在啟動此作業的地區進行。舉例來說,如果您在美國啟動支援續傳的上傳作業,並將工作階段 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 的要求不需簽署,任何人都能使用該 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 個位元組開始保存您傳送的資料。

後續步驟