本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用檢查總和保護資料完整性
<a name="s3-checksums"></a>

Amazon Simple Storage Service (Amazon S3) 可讓您在上傳物件時指定檢查總和。當您指定檢查總和時，它會與 物件一起存放，並在下載物件時進行驗證。

當您傳輸檔案時，檢查總和可提供多一層的資料完整性。使用檢查總和，您可以透過確認收到的檔案符合原始檔案來驗證資料一致性。如需使用 Amazon S3 檢查總和的詳細資訊，請參閱 [Amazon Simple Storage Service 使用者指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html)，包括[支援的演算法](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html#using-additional-checksums)。

您可以靈活地選擇最符合您需求的演算法，並讓 SDK 計算檢查總和。或者，您可以使用其中一個支援的演算法來提供預先計算的檢查總和值。

**注意**  
從 1.4.0 版開始 適用於 Kotlin 的 AWS SDK，會自動計算上傳的`CRC32`檢查總和，以提供預設完整性保護。如果您未提供預先計算的檢查總和值，或者您未指定 SDK 應該用來計算檢查總和的演算法，則 SDK 會計算此檢查總和。  
SDK 也提供全域設定，用於外部設定的資料完整性保護，您可以在 [AWS SDKs和工具參考指南](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html)中閱讀這些保護。

我們討論兩個請求階段的檢查總和：上傳物件和下載物件。

## 上傳物件
<a name="use-service-S3-checksum-upload"></a>

您可以使用 [https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3/put-object.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3/put-object.html)函數搭配請求參數，搭配適用於 Kotlin 的 SDK 將物件上傳至 Amazon S3。請求資料類型提供 `checksumAlgorithm` 屬性，以啟用檢查總和運算。 

下列程式碼片段顯示使用`CRC32`檢查總和上傳物件的請求。當 SDK 傳送請求時，它會計算`CRC32`檢查總和並上傳物件。Amazon S3 會將檢查總和與 物件一起存放。

```
val request = PutObjectRequest {
    bucket = "{{amzn-s3-demo-bucket}}"
    key = "{{key}}"
    checksumAlgorithm = ChecksumAlgorithm.CRC32
}
```

如果您未隨請求提供檢查總和演算法，檢查總和行為會根據您使用的 SDK 版本而有所不同，如下表所示。

**未提供檢查總和演算法時的檢查總和行為**


| Kotlin SDK 版本 | 檢查總和行為 | 
| --- | --- | 
| 早於 1.4.0 | SDK 不會自動計算以 CRC 為基礎的檢查總和，並在請求中提供它。 | 
| 1.4.0 或更新版本 | SDK 使用`CRC32`演算法來計算檢查總和，並在請求中提供檢查總和。Amazon S3 透過計算自己的`CRC32`檢查總和來驗證傳輸的完整性，並將其與 SDK 提供的檢查總和進行比較。如果檢查總和相符，檢查總和會與 物件一起儲存。 | 

### 使用預先計算的檢查總和值
<a name="use-service-S3-checksum-upload-pre"></a>

隨請求提供的預先計算檢查總和值會停用 SDK 的自動運算，並改用提供的值。

下列範例顯示具有預先計算 SHA256 檢查總和的請求。

```
val request = PutObjectRequest {
    bucket = "{{amzn-s3-demo-bucket}}"
    key = "{{key}}"
    body = ByteStream.fromFile(File("file_to_upload.txt"))
    checksumAlgorithm = ChecksumAlgorithm.SHA256
    checksumSha256 = "cfb6d06da6e6f51c22ae3e549e33959dbb754db75a93665b8b579605464ce299"
}
```

如果 Amazon S3 判斷指定演算法的檢查總和值不正確，則服務會傳回錯誤回應。

### 分段上傳
<a name="use-service-S3-checksum-upload-multi"></a>

您也可以使用具有分段上傳的檢查總和。

 您必須在`CreateMultipartUpload`請求和每個`UploadPart`請求中指定檢查總和演算法。最後，您必須在 中指定每個部分的檢查總和`CompleteMultipartUpload`。下列範例說明如何使用指定的檢查總和演算法建立分段上傳。

```
val multipartUpload = s3.createMultipartUpload {
    bucket = "{{amzn-s3-demo-bucket}}"
    key = "{{key}}"
    checksumAlgorithm = ChecksumAlgorithm.Sha1
}

val partFilesToUpload = listOf("data-part1.csv", "data-part2.csv", "data-part3.csv")

val completedParts = partFilesToUpload
    .mapIndexed { i, fileName ->
        val uploadPartResponse = s3.uploadPart {
            bucket = "amzn-s3-demo-bucket"
            key = "key"
            body = ByteStream.fromFile(File(fileName))
            uploadId = multipartUpload.uploadId
            partNumber = i + 1 // Part numbers begin at 1.
            checksumAlgorithm = ChecksumAlgorithm.Sha1
        }

        CompletedPart {
            eTag = uploadPartResponse.eTag
            partNumber = i + 1
            checksumSha1 = uploadPartResponse.checksumSha1
        }
    }

s3.completeMultipartUpload {
    uploadId = multipartUpload.uploadId
    bucket = "{{amzn-s3-demo-bucket}}"
    key = "{{key}}"
    multipartUpload {
        parts = completedParts
    }
}
```

## 下載物件
<a name="use-service-S3-checksum-download"></a>

當您使用 [getObject](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3/-s3-client/get-object.html) getObject方法下載物件時，開發套件會在當 的建置器 `checksumMode` 屬性`GetObjectRequest`設定為 時`ChecksumMode.Enabled`。

以下程式碼片段中的請求會指示 SDK 透過計算檢查總和並比較值來驗證回應中的檢查總和。

```
val request = GetObjectRequest {
    bucket = "{{amzn-s3-demo-bucket}}"
    key = "{{key}}"
    checksumMode = ChecksumMode.Enabled
}
```

**注意**  
如果物件未使用檢查總和上傳，則不會進行驗證。

如果您使用 SDK 版本 1.4.0 或更新版本，軟體開發套件會自動檢查`getObject`請求的完整性，而不會`checksumMode = ChecksumMode.Enabled`新增至請求。

### 非同步驗證
<a name="service-s3-checksum-getObject-kotlin-asyncValidation"></a>

由於適用於 Kotlin 的 SDK 會在從 Amazon S3 下載物件時使用串流回應，因此檢查總和將在您取用物件時計算。因此，*您必須*使用 物件，才能驗證檢查總和。

下列範例顯示如何完全使用回應來驗證檢查總和。

```
val request = GetObjectRequest {
    bucket = "{{amzn-s3-demo-bucket}}"
    key = "{{key}}"
    checksumMode = checksumMode.Enabled
}

val response = s3Client.getObject(request) {
    println(response.body?.decodeToString()) // Fully consume the object.
    // The checksum is valid.
}
```

相反地，以下範例中的程式碼不會以任何方式使用 物件，因此檢查總和不會進行驗證。

```
s3Client.getObject(request) {
    println("Got the object.")
}
```

如果 SDK 計算的檢查總和不符合與回應一起傳送的預期檢查總和，則 SDK 會擲回 `ChecksumMismatchException`。