本頁討論 Cloud Storage 中的可續傳上傳作業。建議使用可續傳上傳功能上傳大型檔案,因為上傳期間如果發生網路問題,您不需要從頭開始上傳。
簡介
如因通訊問題導致資料傳輸過程遭到中斷,之後可透過可繼續上傳功能繼續執行資料移轉作業。支援續傳的上傳作業會傳送多個要求,每個要求都包含您要上傳的物件部分。這與單一要求上傳不同,後者會在單一要求中包含所有物件資料,如果中途失敗,就必須從頭開始。
如果上傳大型檔案或透過連線速度緩慢的網路上傳檔案,請使用支援續傳的機制。如需使用支援續傳的上傳作業時的檔案大小截斷範例,請參閱上傳大小注意事項。
支援續傳的上傳作業必須在啟動後一週內完成,但隨時可以取消。
只有完成的可續傳上傳作業才會顯示在值區中,並視情況取代同名的現有物件。
物件的建立時間是以上傳完成時間為準。
使用者設定的物件中繼資料會指定在初始要求中。 上傳完成後,系統就會將這項中繼資料套用至物件。
如果您在最終要求中加入以
X-Goog-Meta-
為前置字元標頭,JSON API 也支援在最終要求中設定自訂中繼資料。
- 完成可續傳的上傳作業會視為一項 A 級作業。
工具和 API 如何使用支援續傳的上傳作業
視您與 Cloud Storage 的互動方式而定,系統可能會自動為您管理可續傳的檔案上傳作業。本節說明不同工具的可續傳上傳行為,並提供指引,協助您為應用程式設定適當的緩衝區大小。
控制台
Google Cloud 控制台會自動為您管理可續傳的上傳作業。不過,如果在上傳期間重新整理或離開控制台,上傳作業就會取消。Google Cloud
指令列
使用 gcloud CLI 將資料上傳至 Cloud Storage 時,gcloud storage cp
和 gcloud storage rsync
指令會採用可續傳的上傳方式。如果上傳作業中斷,請執行與開始上傳時相同的指令,即可繼續上傳。如要繼續上傳多個檔案,請使用 --no-clobber
旗標,避免重新上傳已成功上傳的檔案。
用戶端程式庫
執行可恢復上傳作業時,用戶端程式庫會充當 Cloud Storage JSON API 的包裝函式。
C++
storage::Client
中的函式會以不同方式執行:
Client::WriteObject()
一律會執行支援續傳的上傳作業。Client::InsertObject()
一律會執行簡單或多部分上傳作業。Client::UploadFile()
可以執行支援續傳的上傳作業、簡單上傳作業或多部分上傳作業。
根據預設,當物件大於 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 用戶端程式庫提供個別方法,用於多部分和可恢復上傳作業。下列方法一律會執行支援續傳的上傳作業:
Storage#createFrom(BlobInfo, java.io.InputStream, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.io.InputStream, int, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.nio.file.Path, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.nio.file.Path, int, Storage.BlobWriteOption...)
Storage#writer(BlobInfo, Storage.BlobWriteOption...)
Storage#writer(java.net.URL)
預設緩衝區大小為 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=resumable
的 POST 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 個位元組開始保存您傳送的資料。