Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用總和檢查碼驗證資料及偵測變更

為驗證資料完整性並偵測變更，Cloud Storage 建議您在 bucket 之間移轉資料時使用核對和。本頁面說明 Cloud Storage 如何使用核對和，以及如何在傳送要求時指定核對和。

使用核對和防止資料損毀

有時，資料在傳輸至雲端或從雲端傳輸時可能會損毀，原因包括軟體或硬體錯誤、記憶體或路由器錯誤、電力干擾，或是在長時間上傳檔案期間變更來源資料。

為防止資料損毀，Cloud Storage 支援使用 CRC32C 和 MD5 核對和，驗證資料完整性並偵測資料變更。

建議使用 CRC32C 驗證方法執行完整性檢查。系統支援使用 MD5 雜湊值驗證單一檔案上傳作業，但不支援以區塊形式上傳的物件，例如複合物件，以及使用 XML API 多部分上傳作業上傳的物件。

資料寫入的核對和

寫入物件時，用戶端會計算本機檔案的核對和，並附加至物件上傳要求的 HTTP 標頭。伺服器會接收資料酬載、計算自己的檢查碼，並在上傳完成後比較兩個檢查碼，藉此驗證資料。如果總和檢查碼相符，物件就會連同總和檢查碼一併儲存在 Cloud Storage 中。如果核對和不相符，寫入要求會遭到拒絕，並傳回 BadRequestException: 400 錯誤。

資料寫入的伺服器端驗證

Cloud Storage 會在下列情況執行伺服器端驗證：

在物件上傳要求中提供物件的 MD5 或 CRC32C 雜湊值。如要瞭解物件上傳類型，請參閱「物件上傳」。
在 Cloud Storage 執行複製或重寫要求時。對於物件複製和重寫要求，Cloud Storage 會根據與來源物件一併儲存的不可編輯的檢查碼，自動執行伺服器端驗證。

JSON API 單一要求 (媒體) 上傳

如果是 JSON API 媒體上傳作業，您可以在要求的 X-Goog-Hash 標頭中指定總和檢查碼。例如：

curl -X POST --data-binary @Desktop/dog-pic.jpeg \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: image/jpeg" \
    -H "X-Goog-Hash: crc32c=n03x6A==" \
    "https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=dog-pic.jpeg"

JSON API 多部分上傳

如果是 JSON API 多部分上傳，您可以在要求容器中指定核對和，位置可以是物件中繼資料區段，也可以是第三個邊界字串下方。如要瞭解物件的 JSON 結構和有效鍵，請參閱「物件資源表示法」。

以下範例會在要求容器的物件中繼資料部分指定 CRC32C 檢查碼：

--separator_string
Content-Type: application/json; charset=UTF-8

{
"name":"my-document.txt",
"crc32c": "n03x6A=="
}

--separator_string
Content-Type: text/plain

This is a text file.
--separator_string--

以下範例在要求容器的第三個邊界字串中指定 CRC32C 核對和：

--separator_string
Content-Type: application/json; charset=UTF-8

{
"name":"my-document.txt"
}

--separator_string
Content-Type: text/plain

This is a text file.

--separator_string
Content-Type: application/json; charset=UTF-8

{ "crc32c": "n03x6A==" }
--separator_string--

JSON API 支援續傳的上傳作業

如果是 JSON API 支援續傳的上傳作業，您可以在完成上傳作業的最終要求 X-Goog-Hash 標頭中指定核對和。例如：

curl -i -X PUT --data-binary @Desktop/dog-pic.jpeg \
      -H "Content-Length: 2000000" \
      -H "X-Goog-Hash: crc32c=n03x6A==" \
      "SESSION_URI"

最終要求中指定的檢查碼是根據整個物件計算而來，而不只是最終要求中的物件資料。

XML API 單次要求上傳

如果是 XML API 單一要求上傳，您可以在要求的 x-goog-hash 標頭中指定核對和。

例如：

curl -X PUT --data-binary @Desktop/dog-pic.jpeg \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: image/jpeg" \
    -H "x-goog-hash: crc32c=n03x6A==" \
    "https://storage.googleapis.com/my-bucket/dog-pic.jpeg"

XML API 單一要求上傳也接受標準 HTTP Content-MD5 標頭。詳情請參閱「Content-MD5 規格」。

XML API 多部分上傳作業

如果是 XML API 多部分上傳，您可以為每個上傳部分指定檢查碼。如要為上傳部分指定個別核對和，請在該特定部分的要求中加入 x-goog-hash 標頭。

例如：

PUT /dog-pic.jpeg?partNumber=1&uploadId=ABgVH8 HTTP/1.1
Host: my-bucket.storage.googleapis.com
Content-Length: 1000000
x-goog-hash: crc32c=n03x6A==

只有 CRC32C 檢查碼可用於驗證 XML API 多部分上傳的完整性。系統不支援 MD5 總和檢查碼。

gRPC 上傳

使用 gRPC 上傳物件時，無論是單次上傳或可續傳上傳，您都可以在任何上傳要求的第 1 個或最後 1 個 WriteObject 訊息中，指定物件層級核對和。

此外，gRPC 也支援訊息層級的檢查碼。每個 WriteObject 訊息最多可包含 2 MiB 的資料區塊，每個區塊可包含自己的核對和。您可以指定訊息層級的檢查碼，取代或搭配物件層級的檢查碼。

平行複合上傳

如果是平行複合上傳，請對每個元件上傳作業執行完整性檢查，然後在上傳組合要求中使用前置條件，防範競爭狀況。Compose 要求不會進行伺服器端驗證，因此如要進行端對端完整性檢查，請對新的複合式物件執行用戶端驗證。

Google Cloud CLI 複製及重寫

在 gcloud CLI 中，複製到 Cloud Storage bucket 或從中複製的資料會自動驗證。對於 cp、mv 和 rsync 指令，gcloud CLI 會使用 MD5 或 CRC32C 總和檢查碼，判斷來源和目的地物件版本之間是否有差異。如果來源資料的總和檢查碼與目的地資料的總和檢查碼不符，gcloud CLI 會刪除無效副本並列印警告訊息。但這種情況極少發生。如果發生這種情況，請重試作業。

物件完成後，系統會自動進行驗證，無效物件會在 1 到 3 秒內顯示，隨後遭到識別並刪除。此外，gcloud CLI 可能會在上傳完成後、執行驗證前中斷，導致無效物件留在原處。如要避免這些問題，請使用 --content-md5 旗標指定 MD5 雜湊，在將單一檔案上傳至 Cloud Storage 時進行伺服器端驗證。

如果物件沒有 MD5 雜湊值，Google Cloud CLI 會忽略 --content-md5 旗標。

`rsync`的變更偵測

gcloud storage rsync 指令會在下列情況比較核對和，判斷是否要略過移轉作業：

來源和目的地都是 Cloud Storage bucket，且物件在兩個 bucket 中都有 MD5 或 CRC32C 核對和。
物件在來源或目的地中都沒有檔案修改時間 (mtime)。

如果物件在來源和目的地都有 mtime 值 (例如來源和目的地都是檔案系統)，rsync 指令會比較物件的大小和 mtime 值，而不是使用總和檢查碼。同樣地，如果來源是 bucket，目的地是本機檔案系統，rsync 指令會使用來源物件的建立時間做為 mtime 的替代值，且不會使用總和檢查碼。

如果 mtime 和總和檢查碼皆無法使用，rsync 只會比較檔案大小，判斷物件的來源版本和目的地版本之間是否有差異。舉例來說，將複合式物件與不支援 CRC32C 的雲端服務供應商物件進行比較時，mtime 和核對和都無法使用，因為複合式物件沒有 MD5 核對和。

資料寫入的用戶端驗證

您可以發出上傳物件中繼資料的要求、比較上傳物件的雜湊值與預期值，並在不符時刪除物件，藉此在用戶端驗證上傳內容。如果上傳開始時不知道物件的 MD5 或 CRC32C 雜湊值，這個方法就很有用。

下表列出支援物件寫入檢查碼的各 Cloud Storage 用戶端最低版本。

客戶	支援物件寫入核對和的版本
Cloud Storage C++ 用戶端程式庫	2.46 以上版本
Cloud Storage Go 用戶端程式庫	1.60.0 以上版本
Cloud Storage Java 用戶端程式庫	2.62 以上版本
Cloud Storage Node.js 用戶端程式庫	7.19.0 以上版本
Cloud Storage PHP 用戶端程式庫	1.51.0 以上版本
Cloud Storage Python 用戶端程式庫	3.7.0 以上版本
Cloud Storage Ruby 用戶端程式庫	1.60.0
Cloud Storage .NET 用戶端程式庫	2.3.0 以上版本。建議使用 4.15.0，這個版本提供伺服器端檢查碼驗證。
Cloud Storage 連接器	3.0.x Cloud Storage 連接器的 3.0.18 以上版本 3.1.14 以上版本 (適用於 3.1.x Cloud Storage 連接器) 4.0.3 以上版本 (適用於 4.0.x Cloud Storage 連接器)
Cloud Storage FUSE	3.8.0 以上版本
Google Cloud CLI	注意：Google Cloud CLI 只會在物件上傳完成後，執行物件完整性驗證。

資料讀取和下載的核對和

如果是物件讀取和下載作業，伺服器會在回應中傳送物件及其儲存的總和檢查碼。用戶端會根據收到的位元組，計算讀取或下載檔案的核對和，並比較兩個核對和，驗證資料完整性。

讀取和下載作業的用戶端驗證

根據預設，所有 Cloud Storage 用戶端程式庫 SDK 都支援計算物件下載和讀取作業的總和檢查碼。下表提供各用戶端程式庫 SDK 的資訊，說明如何停用物件下載或讀取檢查碼。

用戶端程式庫	停用物件讀取或下載核對和的操作說明
Cloud Storage C++ 用戶端程式庫	在 C++ 用戶端程式庫中，將 `DownloadChecksumValidationOption` 設為 `ChecksumAlgorithm::kNone` 值，即可停用核對和驗證。
Cloud Storage Go 用戶端程式庫	在 Go 用戶端程式庫中，您可以在初始化時提供讀取器選項，藉此停用核對和驗證。呼叫 `NewReader` 時傳遞 `WithDisableReaderChecksum()`，或呼叫 `NewMultiRangeDownloader` 時傳遞 `WithDisableMRDReadChecksum()`。
Cloud Storage Java 用戶端程式庫	如要停用 Java 用戶端程式庫中讀取路徑的內部 CRC32C 核對和驗證功能，請傳遞 JVM 系統屬性 `-Dcom.google.cloud.storage.Hasher.read=disabled`，這會關閉讀取的內部雜湊器。如要全面停用讀取和寫入作業的檢查碼，請改用 `-Dcom.google.cloud.storage.Hasher.default=disabled`。
Cloud Storage Node.js 用戶端程式庫	在 Node.js 用戶端程式庫中，您可以在提供給下載方法呼叫的設定選項物件中傳遞 `{ validation: false }`，藉此停用核對和驗證。
Cloud Storage PHP 用戶端程式庫	在 PHP 用戶端程式庫中，呼叫下載方法時，在關聯選項陣列 `($options['validate'])` 中傳遞 `'validate' => false` 或 `'validate' => 'none'`，即可停用 JSON 和 XML API 讀取路徑的核對和驗證。
Cloud Storage Python 用戶端程式庫	在 Python 用戶端程式庫中，停用核對和驗證取決於用戶端傳輸：如果是 JSON 用戶端，請傳遞 `checksum=None` (方法中支援，例如 `download_to_file`)，如果是 gRPC 用戶端，請設定 `enable_checksum=False`。
Cloud Storage Ruby 用戶端程式庫	在 Ruby 用戶端程式庫中，您可以將關鍵字引數 (`checksum:` 或 `verify:`) 直接傳遞至下載方法，並明確設定 `verify: none` 或 `verify: false`，即可停用總和檢查碼驗證。
Cloud Storage .NET 用戶端程式庫	在 .NET 用戶端程式庫中，只要將傳遞至下載方法呼叫的 `DownloadObjectOptions` 物件的 `ChecksumValidation` 屬性設為 `DownloadValidationMode.Never`，即可停用檢查碼驗證。

對下載或讀取的物件執行資料完整性檢查

在某些情況下，應用程式可能需要使用收到的位元組，獨立計算下載或讀取檔案的核對和，並與伺服器提供的雜湊值進行比較，以驗證資料完整性。

如要對下載的資料執行完整性檢查，請在收到資料時計算核對和，並將結果與伺服器提供的核對和進行比較。

伺服器端核對和是以儲存在 Cloud Storage 中的完整物件為依據，因此下列類型的下載內容無法與伺服器提供的核對和進行驗證：

經過解壓縮轉碼的下載內容：伺服器提供的核對和代表壓縮狀態的物件，而提供的資料已移除壓縮，因此具有不同的核對和值。
僅包含部分物件資料的回應：Range 要求會產生這類回應。

gRPC 範圍讀取是這項規則的例外，支援端對端驗證。在 gRPC 範圍讀取中，Cloud Storage 會在串流的每個個別回應區塊中加入專屬的 CRC32C 核對和，藉此驗證資料，讓用戶端立即驗證特定資料區塊在傳輸過程中是否損毀。為了進行更廣泛的驗證，串流也會提供整個物件的完整核對和，進階用戶端可以使用這個核對和計算滾動總和，並驗證較大檔案的完整性。

如果應用程式需要讀取物件範圍，而不是一次讀取完整物件，建議使用 gRPC。否則，建議您只在收到最後一個偏移量後，使用範圍要求重新啟動完整物件的下載作業，這樣您就能在完整下載完成後計算及驗證核對和。

驗證下載內容時，如果計算出的核對和與伺服器提供的核對和不符，表示資料在傳輸過程中損毀。在這些情況下，您應捨棄損毀的資料，並使用建議的重試邏輯重試要求。

後續步驟

瞭解 Cloud Storage 中的物件上傳和物件下載。
瞭解 Cloud Storage 的重試策略。