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

# 在物件層級設定 S3 儲存貯體金鑰
<a name="configuring-bucket-key-object"></a>

當您使用 REST API、 AWS SDKs 或 執行 PUT 或 COPY 操作時 AWS CLI，您可以透過新增具有 `true`或 `false`值的`x-amz-server-side-encryption-bucket-key-enabled`請求標頭，在物件層級啟用或停用 S3 儲存貯體金鑰。S3 儲存貯體金鑰透過減少從 Amazon S3 到 的請求流量，減少使用 AWS Key Management Service (AWS KMS) (SSE-KMS) 的伺服器端加密成本 AWS KMS。如需詳細資訊，請參閱[使用 Amazon S3 儲存貯體金鑰降低 SSE-KMS 的成本](bucket-key.md)。

當您使用 PUT 或 COPY 操作為物件設定 S3 儲存貯體金鑰時，Amazon S3 只會更新該物件的設定。目的地儲存貯體的 S3 儲存貯體金鑰設定不會變更。如果您將 KMS 加密物件的 PUT 或 COPY 請求提交至啟用 S3 儲存貯體金鑰的儲存貯體，除非您停用請求標頭中的金鑰，否則物件層級操作將自動使用 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 Operations 大量執行物件操作](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 儲存貯體金鑰。
+ [CreateMutlipartUpload](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 範例，在物件層級設定 S3 儲存貯體金鑰，做為`PutObject`請求的一部分。

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