[适用于 JavaScript 的 AWS SDK V3 API 参考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)详细描述了 适用于 JavaScript 的 AWS SDK 版本 3 (V3) 的所有 API 操作。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 Amazon S3 校验和实现数据完整性保护
<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 计算校验和。或者，您也可以使用任一受支持的算法，提供预先计算好的校验和值。

**注意**  
从 适用于 JavaScript 的 AWS SDK 3.729.0 开始，该 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>

您可以使用的[PutObject](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectCommand/)命令将对象上传到 Amazon S3 `S3Client`。请使用 `PutObjectRequest` 生成器的 `ChecksumAlgorithm` 参数启用校验和计算并指定算法。请参阅[支持的校验和算法](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html#using-additional-checksums)，获取有效值。

以下代码片段展示了上传具有 CRC-32 校验和的对象的请求。当 SDK 发送此请求时，它会计算 CRC-32 校验和并上传对象。Amazon S3 将校验和与对象一起存储。

```
import { ChecksumAlgorithm, S3 } from "@aws-sdk/client-s3";

const client = new S3();
const response = await client.putObject({
  Bucket: "my-bucket",
  Key: "my-key",
  Body: "Hello, world!",
  ChecksumAlgorithm: ChecksumAlgorithm.CRC32,
});
```

如果您未在请求中提供校验和算法，则校验和行为将根据您使用的 SDK 版本而异，具体如下表所示。

**未提供校验和算法时的校验和行为**


|  JavaScript 版本的 SDK | 校验和行为 | 
| --- | --- | 
| 早于 3.729.0 | SDK 不会自动计算基于 CRC 的校验和，也不会在请求中提供该值。 | 
| 3.729.0 或更高版本 | SDK 采用 CRC32 算法计算校验和，并在请求中提供该值。Amazon S3 通过计算自己的 CRC32 校验和并将其与 SDK 提供的校验和进行对比，从而验证传输的完整性。如果校验和匹配，则校验和将与对象一起保存。 | 

如果 SDK 计算的校验和与 Amazon S3 在收到请求时计算的校验和不匹配，则会返回错误。

### 使用预先计算的校验和值
<a name="use-service-S3-checksum-upload-pre"></a>

与请求一起提供的预先计算校验和值会禁用 SDK 的自动计算，而是使用提供的值。

以下示例展示了具有预先计算的 SHA-256 校验和的请求。

```
import { S3 } from "@aws-sdk/client-s3";
import { createHash } from "node:crypto";

const client = new S3();

const Body = "Hello, world!";
const ChecksumSHA256 = await createHash("sha256").update(Body).digest("base64");

const response = await client.putObject({
  Bucket: "my-bucket",
  Key: "my-key",
  Body,
  ChecksumSHA256,
});
```

如果 Amazon S3 确定指定算法的校验和值不正确，服务就会返回错误响应。

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

您也可以将校验和用于分段上传。 适用于 JavaScript 的 AWS SDK 可以使用`Upload`库选项从 `@aws-sdk/lib-storage` from 对分段上传使用校验和。

```
import { ChecksumAlgorithm, S3 } from "@aws-sdk/client-s3";
import { Upload } from "@aws-sdk/lib-storage";
import { createReadStream } from "node:fs";

const client = new S3();
const filePath = "/path/to/file";
const Body = createReadStream(filePath);

const upload = new Upload({
  client,
  params: {
    Bucket: "my-bucket",
    Key: "my-key",
    Body,
    ChecksumAlgorithm: ChecksumAlgorithm.CRC32,
  },
});
await upload.done();
```