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

# 使用檢查總和保護資料完整性
<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 計算檢查總和。或者，您可以使用其中一個支援的演算法來提供預先計算的檢查總和值。

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

**重要**  
若要使用`CRC32C`演算法，您的 PHP 環境需要[安裝 AWS 通用執行期 (AWS CRT) 延伸](guide_crt.md)模組。

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

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

您可以使用 的 [putObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) 方法，將物件上傳至 Amazon S3`S3Client`。使用參數陣列中的 `ChecksumAlgorithm`對來啟用檢查總和運算並指定演算法。

```
$client = new \Aws\S3\S3Client(['region' => 'us-east-2']); // See the note below.
$result = $client->putObject([
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key' => 'key',
        'ChecksumAlgorithm' => 'CRC32',
        'Body' => 'Object contents to test the checksum.'
]);
```

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

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


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

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

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

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

```
use Aws\S3\S3Client;
use GuzzleHttp\Psr7;

$client = new S3Client([
    'region' => 'us-east-1',
]);

// Calculate the SHA256 checksum of the contents to be uploaded.
$contents = 'Object contents to test the checksum.';
$body = Psr7\Utils::streamFor($contents);
$sha256 = base64_encode(Psr7\Utils::hash($body, 'sha256', true));

$result = $client->putObject([
    'Bucket' => 'amzn-s3-demo-bucket',
    'Key' => 'key',
    'Body' => $body,
    'ChecksumSHA256' => $sha256
]);
```

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

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

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

 如下列範例所示，在[`MultipartUploader`建構函數](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html#___construct)`params`陣列中將檢查總和演算法指定為鍵/值對。

```
$s3Client = new S3Client([
    'region' => 'us-east-1'
]);

$stream = fopen("/path/to/large/file", "r");

$mpUploader = new MultipartUploader($s3Client, $stream, [
    'bucket' => 'amzn-s3-demo-bucket',
    'key' => 'key',
    'params' => ['ChecksumAlgorithm' => 'CRC32']
]);
```

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

當您使用 [getObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject) getObject方法下載物件時，開發套件會在`ChecksumMode`金鑰的值為 時自動驗證檢查總和`enabled`。

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

```
$result = $client->getObject([
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key' => 'test-checksum-key',
        'ChecksumMode' => 'enabled',
]);
```

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