# 在对象级别配置 S3 存储桶密钥
<a name="configuring-bucket-key-object"></a>

当您使用 REST API、AWS SDK 或 AWS CLI 执行 PUT 或 COPY 操作时，您可以通过添加带有 `true` 或 `false` 值的 `x-amz-server-side-encryption-bucket-key-enabled` 请求标头在对象级别启用或禁用 S3 存储桶密钥。S3 存储桶密钥通过减少从 Amazon S3 到 AWS KMS 的请求流量，降低了使用 AWS Key Management Service（AWS KMS）（SSE-KMS）进行服务器端加密的成本。有关更多信息，请参阅 [使用 Amazon S3 存储桶密钥降低 SSE-KMS 的成本](bucket-key.md)。

当您使用 PUT 或 COPY 操作为对象配置 S3 存储桶密钥时，Amazon S3 仅更新该对象的设置。目标存储桶的 S3 存储桶密钥设置不会更改。如果您在启用了 S3 存储桶密钥的存储桶中提交对于 KMS 加密对象的 PUT 或 COPY 请求，则除非您禁用了请求标头中的密钥，否则您的对象级操作将自动使用 S3 存储桶密钥。如果您未为对象指定 S3 存储桶密钥，则 Amazon S3 会将目标存储桶的 S3 存储桶密钥设置应用于该对象。

**先决条件：**  
在将对象配置为使用 S3 存储桶密钥之前，请查看 [启用 S3 存储桶密钥之前需要注意的更改](bucket-key.md#bucket-key-changes)。

**Topics**
+ [

## Amazon S3 批量操作
](#bucket-key-object-bops)
+ [

## 使用 REST API
](#bucket-key-object-rest)
+ [

## 使用适用于 Java 的 AWS SDK（PutObject）
](#bucket-key-object-sdk)
+ [

## 使用 AWS CLI (PutObject)
](#bucket-key-object-cli)

## Amazon S3 批量操作
<a name="bucket-key-object-bops"></a>

要加密现有 Amazon S3 对象，可以使用 Amazon S3 批量操作。您为 S3 批量操作提供了要操作的对象列表，而批量操作调用相应的 API 来执行指定的操作。

您可以使用 [S3 批量操作复制操作](https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops-copy-object.html)复制现有的未加密对象，并将其作为加密对象写回同一存储桶。单个批量操作作业可对数十亿个对象执行指定操作。有关更多信息，请参阅 [使用批量操作批量执行对象操作](batch-ops.md) 和 [使用 Amazon S3 批量操作加密对象](https://aws.amazon.com/blogs/storage/encrypting-objects-with-amazon-s3-batch-operations/)。

## 使用 REST API
<a name="bucket-key-object-rest"></a>

使用 SSE-KMS 时，您可以使用以下 API 操作为对象启用 S3 存储桶密钥：
+ [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) – 上传对象时，您可以指定 `x-amz-server-side-encryption-bucket-key-enabled` 请求标头以在对象级别启用或禁用 S3 存储桶密钥。
+ [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) – 当您复制对象并配置 SSE-KMS 时，您可以指定 `x-amz-server-side-encryption-bucket-key-enabled` 请求标头以为对象启用或禁用 S3 存储桶密钥。
+ [POST 对象](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) – 当您使用 `POST` 操作上传对象并配置 SSE-KMS 时，您可以使用 `x-amz-server-side-encryption-bucket-key-enabled` 表单字段为对象启用或禁用 S3 存储桶密钥。
+ [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) – 当您使用 `CreateMultipartUpload` API 操作上传大型对象并配置 SSE-KMS 时，您可以使用 `x-amz-server-side-encryption-bucket-key-enabled` 请求标头为对象启用或禁用 S3 存储桶密钥。

要在对象级别启用 S3 存储桶密钥，请包含 `x-amz-server-side-encryption-bucket-key-enabled` 请求标头。有关 SSE-KMS 和 REST API 的更多信息，请参阅 [使用 REST API](specifying-kms-encryption.md#KMSUsingRESTAPI)。

## 使用适用于 Java 的 AWS SDK（PutObject）
<a name="bucket-key-object-sdk"></a>

您可以使用以下示例通过 适用于 Java 的 AWS SDK 在对象级别配置 S3 存储桶密钥。

------
#### [ Java ]

```
AmazonS3 s3client = AmazonS3ClientBuilder.standard()
    .withRegion(Regions.DEFAULT_REGION)
    .build();

String bucketName = "amzn-s3-demo-bucket1";
String keyName = "key name for object";
String contents = "file contents";

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, keyName, contents)
    .withBucketKeyEnabled(true);
    
s3client.putObject(putObjectRequest);
```

------

## 使用 AWS CLI (PutObject)
<a name="bucket-key-object-cli"></a>

您可以使用以下 AWS CLI 示例作为 `PutObject` 请求的一部分在对象级别配置 S3 存储桶密钥。

```
aws s3api put-object --bucket amzn-s3-demo-bucket --key object key name --server-side-encryption aws:kms --bucket-key-enabled --body filepath
```