適用於 Java 的 AWS SDK 1.x 已於 2025 年 12 月 31 日end-of-support。我們建議您遷移至 [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html)，以繼續接收新功能、可用性改善和安全性更新。

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

# Amazon S3 使用 的範例 適用於 Java 的 AWS SDK
<a name="examples-s3"></a>

本節提供使用[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)編寫 [Amazon S3](https://aws.amazon.com/s3/) 程式的範例。

**注意**  
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。

**Topics**
+ [建立、列出和刪除 Amazon S3 儲存貯體](examples-s3-buckets.md)
+ [在 Amazon S3 物件上執行操作](examples-s3-objects.md)
+ [管理儲存貯體和物件的 Amazon S3 存取許可](examples-s3-access-permissions.md)
+ [使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取](examples-s3-bucket-policies.md)
+ [使用 TransferManager 進行 Amazon S3 操作](examples-s3-transfermanager.md)
+ [將 Amazon S3 儲存貯體設定為網站](examples-s3-website-configuration.md)
+ [使用 Amazon S3 用戶端加密](examples-crypto.md)

# 建立、列出和刪除 Amazon S3 儲存貯體
<a name="examples-s3-buckets"></a>

中的每個物件 （檔案） Amazon S3 都必須位於代表物件集合 （容器） 的*儲存貯*體中。每個儲存貯體都是由索引*鍵* （名稱） 所知道，該索引鍵必須是唯一的。如需儲存貯體及其組態的詳細資訊，請參閱 Amazon Simple Storage Service 《 使用者指南》中的[使用 Amazon S3 儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html)。

**注意**  
最佳實務  
建議您在 Amazon S3 儲存貯體上啟用 [AbortIncompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html) 生命週期規則。  
此規則 Amazon S3 會指示 中止未在啟動後指定天數內完成的分段上傳。超過設定的時間限制時， 會 Amazon S3 中止上傳，然後刪除不完整的上傳資料。  
如需詳細資訊，請參閱 Amazon S3 《 使用者指南》中的[使用版本控制的儲存貯體生命週期組態](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-bucket-with-versioning.html)。

**注意**  
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。

## 建立儲存貯體
<a name="create-bucket"></a>

使用 AmazonS3 用戶端的 `createBucket`方法。傳回新的[儲存貯體](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Bucket.html)。如果儲存貯體已存在，則 `createBucket`方法將引發例外狀況。

**注意**  
若要在嘗試建立具有相同名稱的儲存貯體之前檢查儲存貯體是否已存在，請呼叫 `doesBucketExist`方法。`true` 如果儲存貯體存在，則會傳回 ，`false`否則傳回 。

 **匯入** 

```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AmazonS3Exception;
import com.amazonaws.services.s3.model.Bucket;

import java.util.List;
```

 **Code** 

```
if (s3.doesBucketExistV2(bucket_name)) {
    System.out.format("Bucket %s already exists.\n", bucket_name);
    b = getBucket(bucket_name);
} else {
    try {
        b = s3.createBucket(bucket_name);
    } catch (AmazonS3Exception e) {
        System.err.println(e.getErrorMessage());
    }
}
return b;
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/CreateBucket.java)。

## 列出儲存貯體
<a name="list-buckets"></a>

使用 AmazonS3 用戶端的 `listBucket`方法。如果成功，則會傳回[儲存貯體](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Bucket.html)清單。

 **匯入** 

```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.Bucket;

import java.util.List;
```

 **Code** 

```
List<Bucket> buckets = s3.listBuckets();
System.out.println("Your {S3} buckets are:");
for (Bucket b : buckets) {
    System.out.println("* " + b.getName());
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/ListBuckets.java)。

## 刪除儲存貯體
<a name="delete-bucket"></a>

您必須先確認儲存 Amazon S3 貯體為空，否則將發生錯誤，才能刪除儲存貯體。如果您有[版本控制的儲存貯](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html)體，您也必須刪除與儲存貯體相關聯的任何版本控制的物件。

**注意**  
[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)依序包含這些步驟，提供刪除 儲存 Amazon S3 貯體及其內容的完整解決方案。

**Topics**
+ [從未版本控制的儲存貯體移除物件，然後再刪除](#remove-objects-from-an-unversioned-bucket-before-deleting-it)
+ [從已版本控制的儲存貯體移除物件，然後再將其刪除](#remove-objects-from-a-versioned-bucket-before-deleting-it)
+ [刪除空的儲存貯體](#delete-an-empty-bucket)

### 從未版本控制的儲存貯體移除物件，然後再刪除
<a name="remove-objects-from-an-unversioned-bucket-before-deleting-it"></a>

使用 AmazonS3 用戶端的 `listObjects`方法擷取物件清單`deleteObject`，並刪除每個物件清單。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.*;

import java.util.Iterator;
```

 **Code** 

```
System.out.println(" - removing objects from bucket");
ObjectListing object_listing = s3.listObjects(bucket_name);
while (true) {
    for (Iterator<?> iterator =
         object_listing.getObjectSummaries().iterator();
         iterator.hasNext(); ) {
        S3ObjectSummary summary = (S3ObjectSummary) iterator.next();
        s3.deleteObject(bucket_name, summary.getKey());
    }

    // more object_listing to retrieve?
    if (object_listing.isTruncated()) {
        object_listing = s3.listNextBatchOfObjects(object_listing);
    } else {
        break;
    }
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)。

### 從已版本控制的儲存貯體移除物件，然後再將其刪除
<a name="remove-objects-from-a-versioned-bucket-before-deleting-it"></a>

如果您使用的是[版本控制的儲存貯](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html)體，您也需要移除儲存貯體中物件的任何存放版本，才能刪除儲存貯體。

使用類似於移除儲存貯體中物件時所使用的模式，透過使用 AmazonS3 用戶端的 `listVersions`方法來列出任何版本控制的物件，然後刪除每個物件`deleteVersion`，以移除版本控制的物件。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.*;

import java.util.Iterator;
```

 **Code** 

```
System.out.println(" - removing versions from bucket");
VersionListing version_listing = s3.listVersions(
        new ListVersionsRequest().withBucketName(bucket_name));
while (true) {
    for (Iterator<?> iterator =
         version_listing.getVersionSummaries().iterator();
         iterator.hasNext(); ) {
        S3VersionSummary vs = (S3VersionSummary) iterator.next();
        s3.deleteVersion(
                bucket_name, vs.getKey(), vs.getVersionId());
    }

    if (version_listing.isTruncated()) {
        version_listing = s3.listNextBatchOfVersions(
                version_listing);
    } else {
        break;
    }
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)。

### 刪除空的儲存貯體
<a name="delete-an-empty-bucket"></a>

從儲存貯體移除物件後 （包括任何版本控制的物件），您可以使用 AmazonS3 用戶端的 `deleteBucket`方法刪除儲存貯體本身。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.*;

import java.util.Iterator;
```

 **Code** 

```
System.out.println(" OK, bucket ready to delete!");
s3.deleteBucket(bucket_name);
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)。

# 在 Amazon S3 物件上執行操作
<a name="examples-s3-objects"></a>

 Amazon S3 物件代表*檔案*或資料集合。每個物件都必須位於儲存[貯](examples-s3-buckets.md)體中。

**注意**  
這些程式碼範例假設您了解[使用 中的資料， 適用於 Java 的 AWS SDK](basics.md)並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。

**Topics**
+ [上傳物件](#upload-object)
+ [列出物件](#list-objects)
+ [下載物件](#download-object)
+ [複製、移動或重新命名物件](#copy-object)
+ [刪除物件](#delete-object)
+ [一次刪除多個物件](#delete-objects)

## 上傳物件
<a name="upload-object"></a>

使用 AmazonS3 用戶端的 `putObject`方法，提供儲存貯體名稱、金鑰名稱和要上傳的檔案。*儲存貯體必須存在，否則會產生錯誤*。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
```

 **Code** 

```
System.out.format("Uploading %s to S3 bucket %s...\n", file_path, bucket_name);
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    s3.putObject(bucket_name, key_name, new File(file_path));
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/PutObject.java)。

## 列出物件
<a name="list-objects"></a>

若要取得儲存貯體中的物件清單，請使用 AmazonS3 用戶端的 `listObjects`方法，並提供儲存貯體的名稱。

`listObjects` 方法會傳回 [ObjectListing](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/ObjectListing.html) 物件，提供儲存貯體中物件的相關資訊。若要列出物件名稱 （金鑰），請使用 `getObjectSummaries`方法取得 [S3ObjectSummary](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3ObjectSummary.html) 物件清單，每個物件都代表儲存貯體中的單一物件。然後呼叫其 `getKey`方法來擷取物件的名稱。

 **匯入** 

```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.ListObjectsV2Result;
import com.amazonaws.services.s3.model.S3ObjectSummary;
```

 **Code** 

```
System.out.format("Objects in S3 bucket %s:\n", bucket_name);
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
ListObjectsV2Result result = s3.listObjectsV2(bucket_name);
List<S3ObjectSummary> objects = result.getObjectSummaries();
for (S3ObjectSummary os : objects) {
    System.out.println("* " + os.getKey());
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/ListObjects.java)。

## 下載物件
<a name="download-object"></a>

使用 AmazonS3 用戶端的 `getObject`方法，將要下載的儲存貯體和物件的名稱傳遞給用戶端。如果成功， 方法會傳回 [S3Object](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3Object.html)。*指定的儲存貯體和物件金鑰必須存在，否則會產生錯誤*。

您可以在 `getObjectContent`上呼叫 ，以取得物件的內容`S3Object`。這會傳回做為標準 Java `InputStream` 物件的 [S3ObjectInputStream](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3ObjectInputStream.html)。

下列範例會從 S3 下載物件，並將其內容儲存至檔案 （使用與物件金鑰相同的名稱）。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.S3Object;
import com.amazonaws.services.s3.model.S3ObjectInputStream;

import java.io.File;
```

 **Code** 

```
System.out.format("Downloading %s from S3 bucket %s...\n", key_name, bucket_name);
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    S3Object o = s3.getObject(bucket_name, key_name);
    S3ObjectInputStream s3is = o.getObjectContent();
    FileOutputStream fos = new FileOutputStream(new File(key_name));
    byte[] read_buf = new byte[1024];
    int read_len = 0;
    while ((read_len = s3is.read(read_buf)) > 0) {
        fos.write(read_buf, 0, read_len);
    }
    s3is.close();
    fos.close();
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
} catch (FileNotFoundException e) {
    System.err.println(e.getMessage());
    System.exit(1);
} catch (IOException e) {
    System.err.println(e.getMessage());
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetObject.java)。

## 複製、移動或重新命名物件
<a name="copy-object"></a>

您可以使用 AmazonS3 用戶端的 `copyObject`方法，將物件從一個儲存貯體複製到另一個儲存貯體。它接受要複製的儲存貯體名稱、要複製的物件，以及目的地儲存貯體名稱。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
```

 **Code** 

```
try {
    s3.copyObject(from_bucket, object_key, to_bucket, object_key);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
System.out.println("Done!");
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/CopyObject.java)。

**注意**  
您可以`copyObject`搭配 [deleteObject](#delete-object) 使用 來**移動**或**重新命名**物件，方法是先將物件複製到新名稱 （您可以使用與來源和目的地相同的儲存貯體），然後從舊位置刪除物件。

## 刪除物件
<a name="delete-object"></a>

使用 AmazonS3 用戶端的 `deleteObject`方法，將要刪除的儲存貯體和物件的名稱傳遞給用戶端。*指定的儲存貯體和物件金鑰必須存在，否則會產生錯誤*。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
```

 **Code** 

```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    s3.deleteObject(bucket_name, object_key);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteObject.java)。

## 一次刪除多個物件
<a name="delete-objects"></a>

使用 AmazonS3 用戶端的 `deleteObjects`方法，您可以將多個物件從相同儲存貯體中刪除，方法是將它們的名稱傳遞至 link：sdk-for-java/v1/reference/com/amazonaws/services/s3/model/DeleteObjectsRequest.html`` 方法。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
```

 **Code** 

```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    DeleteObjectsRequest dor = new DeleteObjectsRequest(bucket_name)
            .withKeys(object_keys);
    s3.deleteObjects(dor);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java)。

# 管理儲存貯體和物件的 Amazon S3 存取許可
<a name="examples-s3-access-permissions"></a>

您可以針對 Amazon S3 儲存貯體和物件使用存取控制清單 (ACLs)，以精細控制 Amazon S3 資源。

**注意**  
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。

## 取得儲存貯體的存取控制清單
<a name="get-the-access-control-list-for-a-bucket"></a>

若要取得儲存貯體的目前 ACL，請呼叫 AmazonS3 的 `getBucketAcl`方法，將儲存*貯體名稱*傳遞給它以進行查詢。此方法會傳回 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件。若要取得清單中的每個存取授權，請呼叫其 `getGrantsAsList` 方法，這會傳回標準 Java [授予](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grant.html)物件清單。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.Grant;
```

 **Code** 

```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    AccessControlList acl = s3.getBucketAcl(bucket_name);
    List<Grant> grants = acl.getGrantsAsList();
    for (Grant grant : grants) {
        System.out.format("  %s: %s\n", grant.getGrantee().getIdentifier(),
                grant.getPermission().toString());
    }
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java)。

## 設定儲存貯體的存取控制清單
<a name="set-the-access-control-list-for-a-bucket"></a>

若要新增或修改儲存貯體的 ACL 許可，請呼叫 AmazonS3 的 `setBucketAcl`方法。它需要 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件，其中包含要設定的承授者和存取層級清單。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.EmailAddressGrantee;
```

 **Code** 

```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    // get the current ACL
    AccessControlList acl = s3.getBucketAcl(bucket_name);
    // set access for the grantee
    EmailAddressGrantee grantee = new EmailAddressGrantee(email);
    Permission permission = Permission.valueOf(access);
    acl.grantPermission(grantee, permission);
    s3.setBucketAcl(bucket_name, acl);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

**注意**  
您可以直接使用承授者類別提供[承授](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grantee.html)者的唯一識別符，或使用 [EmailAddressGrantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/EmailAddressGrantee.html) 類別來透過電子郵件設定承授者，如同我們在這裡所做的。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetAcl.java)。

## 取得物件的存取控制清單
<a name="get-the-access-control-list-for-an-object"></a>

若要取得物件的目前 ACL，請呼叫 AmazonS3 的 `getObjectAcl`方法，將要查詢的儲存*貯體名稱*和*物件名稱*傳遞給它。如同 `getBucketAcl`，此方法會傳回 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件，您可以用來檢查每個[授與](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grant.html)。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.Grant;
```

 **Code** 

```
try {
    AccessControlList acl = s3.getObjectAcl(bucket_name, object_key);
    List<Grant> grants = acl.getGrantsAsList();
    for (Grant grant : grants) {
        System.out.format("  %s: %s\n", grant.getGrantee().getIdentifier(),
                grant.getPermission().toString());
    }
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java)。

## 設定物件的存取控制清單
<a name="set-the-access-control-list-for-an-object"></a>

若要新增或修改物件的 ACL 許可，請呼叫 AmazonS3 的 `setObjectAcl`方法。它需要 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件，其中包含要設定的承授者和存取層級清單。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.EmailAddressGrantee;
```

 **Code** 

```
    try {
        // get the current ACL
        AccessControlList acl = s3.getObjectAcl(bucket_name, object_key);
        // set access for the grantee
        EmailAddressGrantee grantee = new EmailAddressGrantee(email);
        Permission permission = Permission.valueOf(access);
        acl.grantPermission(grantee, permission);
        s3.setObjectAcl(bucket_name, object_key, acl);
    } catch (AmazonServiceException e) {
        System.err.println(e.getErrorMessage());
        System.exit(1);
    }
}
```

**注意**  
您可以直接使用承授者類別提供[承授](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grantee.html)者的唯一識別符，或使用 [EmailAddressGrantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/EmailAddressGrantee.html) 類別來透過電子郵件設定承授者，如同我們在這裡所做的。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetAcl.java)。

## 詳細資訊
<a name="more-information"></a>
+  Amazon S3 API 參考中的 [GET 儲存貯體 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETacl.html) 
+  Amazon S3 API 參考中的 [PUT 儲存貯體 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTacl.html) 
+  Amazon S3 API 參考中的 [GET 物件 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETacl.html) 
+  Amazon S3 API 參考中的 [PUT 物件 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUTacl.html) 

# 使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取
<a name="examples-s3-bucket-policies"></a>

您可以設定、取得或刪除儲存*貯體政策*，以管理對儲存 Amazon S3 貯體的存取。

## 設定儲存貯體政策
<a name="set-s3-bucket-policy"></a>

您可以透過下列方式設定特定 S3 儲存貯體的儲存貯體政策：
+ 呼叫 AmazonS3 用戶端的 ，`setBucketPolicy`並提供 [SetBucketPolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/SetBucketPolicyRequest.html) 
+ 使用採用儲存貯體名稱和政策文字的`setBucketPolicy`過載直接設定政策 (JSON 格式）

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.auth.policy.Policy;
import com.amazonaws.auth.policy.Principal;
```

 **Code** 

```
    s3.setBucketPolicy(bucket_name, policy_text);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

### 使用政策類別來產生或驗證政策
<a name="use-s3-bucket-policy-class"></a>

提供儲存貯體政策給 時`setBucketPolicy`，您可以執行下列動作：
+ 直接將政策指定為 JSON 格式文字的字串
+ 使用 政策類別建置[政策](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/policy/Policy.html) 

透過使用 `Policy`類別，您不需要擔心文字字串的格式是否正確。若要從 `Policy`類別取得 JSON 政策文字，請使用其 `toJson` 方法。

 **匯入** 

```
import com.amazonaws.auth.policy.Resource;
import com.amazonaws.auth.policy.Statement;
import com.amazonaws.auth.policy.actions.S3Actions;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
```

 **Code** 

```
        new Statement(Statement.Effect.Allow)
                .withPrincipals(Principal.AllUsers)
                .withActions(S3Actions.GetObject)
                .withResources(new Resource(
                        "{region-arn}s3:::" + bucket_name + "/*")));
return bucket_policy.toJson();
```

`Policy` 類別也提供`fromJson`一種方法，可嘗試使用傳入的 JSON 字串來建置政策。方法會進行驗證，以確保文字可轉換為有效的政策結構，如果政策文字無效`IllegalArgumentException`， 便會失敗。

```
Policy bucket_policy = null;
try {
    bucket_policy = Policy.fromJson(file_text.toString());
} catch (IllegalArgumentException e) {
    System.out.format("Invalid policy text in file: \"%s\"",
            policy_file);
    System.out.println(e.getMessage());
}
```

您可以使用此技術預先驗證從檔案或其他方式讀取的政策。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java)。

## 取得儲存貯體政策
<a name="get-s3-bucket-policy"></a>

若要擷取 儲存 Amazon S3 貯體的政策，請呼叫 AmazonS3 用戶端的 `getBucketPolicy`方法，將儲存貯體的名稱傳遞給它以從中取得政策。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
```

 **Code** 

```
  try {
      BucketPolicy bucket_policy = s3.getBucketPolicy(bucket_name);
      policy_text = bucket_policy.getPolicyText();
  } catch (AmazonServiceException e) {
      System.err.println(e.getErrorMessage());
      System.exit(1);
  }
```

如果命名的儲存貯體不存在，如果您無法存取它，或如果它沒有儲存貯體政策，`AmazonServiceException`則會擲出 。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetBucketPolicy.java)。

## 刪除儲存貯體政策
<a name="delete-s3-bucket-policy"></a>

若要刪除儲存貯體政策，請呼叫 AmazonS3 用戶端的 `deleteBucketPolicy`，並提供儲存貯體名稱。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
```

 **Code** 

```
  try {
      s3.deleteBucketPolicy(bucket_name);
  } catch (AmazonServiceException e) {
      System.err.println(e.getErrorMessage());
      System.exit(1);
  }
```

即使儲存貯體還沒有政策，此方法也會成功。如果您指定的儲存貯體名稱不存在，或者您無法存取儲存貯體，`AmazonServiceException`則會擲回 。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucketPolicy.java)。

## 詳細資訊
<a name="more-info"></a>
+  Amazon Simple Storage Service 《 使用者指南》中的[存取政策語言概觀](https://docs.aws.amazon.com/AmazonS3/latest/dev/access-policy-language-overview.html) 
+  Amazon Simple Storage Service 《 使用者指南》中的[儲存貯體政策範例](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) 

# 使用 TransferManager 進行 Amazon S3 操作
<a name="examples-s3-transfermanager"></a>

您可以使用 適用於 Java 的 AWS SDK TransferManager 類別，可靠地將檔案從本機環境傳輸到另一個 S3 位置 Amazon S3 ，以及將物件複製到另一個位置。 `TransferManager`可以取得傳輸進度，並暫停或繼續上傳和下載。

**注意**  
最佳實務  
建議您在 Amazon S3 儲存貯體上啟用 [AbortIncompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html) 生命週期規則。  
此規則 Amazon S3 會指示 中止在啟動後指定天數內未完成的分段上傳。超過設定的時間限制時， 會 Amazon S3 中止上傳，然後刪除不完整的上傳資料。  
如需詳細資訊，請參閱 Amazon S3 《 使用者指南[》中的使用版本控制的儲存貯體生命週期組態](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-bucket-with-versioning.html)。

**注意**  
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。

## 上傳檔案和目錄
<a name="transfermanager-uploading"></a>

TransferManager 可以將檔案、檔案清單和目錄上傳至您[先前建立](examples-s3-buckets.md#create-bucket)的任何儲存 Amazon S3 貯體。

**Topics**
+ [上傳單一檔案](#transfermanager-upload-file)
+ [上傳檔案清單](#transfermanager-upload-file-list)
+ [上傳目錄](#transfermanager-upload-directory)

### 上傳單一檔案
<a name="transfermanager-upload-file"></a>

呼叫 TransferManager 的 `upload`方法，提供儲存 Amazon S3 貯體名稱、金鑰 （物件） 名稱，以及代表要上傳之檔案的標準 Java [檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
```

 **Code** 

```
File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Upload xfer = xfer_mgr.upload(bucket_name, key_name, f);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    //  or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

`upload` 方法*會立即*傳回，提供 `Upload` 物件以用來檢查傳輸狀態或等待它完成。

請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java)。

### 上傳檔案清單
<a name="transfermanager-upload-file-list"></a>

若要在一個操作中上傳多個檔案，請呼叫 TransferManager`uploadFileList` 方法，並提供下列項目：
+ 儲存 Amazon S3 貯體名稱
+ *金鑰字首*，以建立物件的名稱開頭 （在儲存貯體中放置物件的路徑）
+ 代表從中建立[檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)路徑之相對目錄的檔案物件
+ [清單](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/List.html)物件，其中包含一組要上傳[的檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
```

 **Code** 

```
ArrayList<File> files = new ArrayList<File>();
for (String path : file_paths) {
    files.add(new File(path));
}

TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    MultipleFileUpload xfer = xfer_mgr.uploadFileList(bucket_name,
            key_prefix, new File("."), files);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。

傳回的 [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) 物件`uploadFileList`可用來查詢傳輸狀態或進度。如需詳細資訊，請參閱使用 ProgressListener [輪詢傳輸的目前進度](#transfermanager-get-progress-polling)和取得傳輸進度。 [ ProgressListener](#transfermanager-progress-listener) 

您也可以使用 `MultipleFileUpload`的 `getSubTransfers`方法，取得每個要傳輸檔案的個別`Upload`物件。如需詳細資訊，請參閱[取得子轉移進度](#transfermanager-get-subtransfer-progress)。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java)。

### 上傳目錄
<a name="transfermanager-upload-directory"></a>

您可以使用 TransferManager 的 `uploadDirectory`方法上傳整個檔案目錄，並可選擇以遞迴方式複製子目錄中的檔案。您提供儲存 Amazon S3 貯體名稱、S3 金鑰字首、代表要複製之本機目錄[的檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件，以及指出是否要以遞迴方式 (*true* 或 *false*) 複製子目錄`boolean`的值。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
```

 **Code** 

```
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    MultipleFileUpload xfer = xfer_mgr.uploadDirectory(bucket_name,
            key_prefix, new File(dir_path), recursive);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。

傳回的 [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) 物件`uploadFileList`可用來查詢傳輸狀態或進度。如需詳細資訊，請參閱使用 ProgressListener [輪詢傳輸的目前進度](#transfermanager-get-progress-polling)和取得傳輸進度。 [ ProgressListener](#transfermanager-progress-listener) 

您也可以使用 `MultipleFileUpload`的 `getSubTransfers`方法，取得每個要傳輸檔案的個別`Upload`物件。如需詳細資訊，請參閱[取得子轉移進度](#transfermanager-get-subtransfer-progress)。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java)。

## 下載檔案或目錄
<a name="transfermanager-downloading"></a>

使用 TransferManager 類別從中下載單一檔案 (Amazon S3 物件） 或目錄 ( Amazon S3 儲存貯體名稱後接物件字首） Amazon S3。

**Topics**
+ [下載單一檔案](#transfermanager-download-file)
+ [下載目錄](#tranfermanager-download-directory)

### 下載單一檔案
<a name="transfermanager-download-file"></a>

使用 TransferManager 的 `download`方法，提供儲存 Amazon S3 貯體名稱，其中包含您要下載的物件、金鑰 （物件） 名稱，以及代表要在本機系統上建立之檔案的檔案[https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Download;
import com.amazonaws.services.s3.transfer.MultipleFileDownload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;

import java.io.File;
```

 **Code** 

```
File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Download xfer = xfer_mgr.download(bucket_name, key_name, f);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得有關使用 `waitForCompletion` 成功完成轉接的資訊，然後再呼叫 TransferManager 的 `shutdownNow`方法。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java)。

### 下載目錄
<a name="tranfermanager-download-directory"></a>

若要從中下載一組共用常見金鑰字首 （類似於檔案系統上的目錄） 的檔案 Amazon S3，請使用 TransferManager`downloadDirectory` 方法。方法採用儲存 Amazon S3 貯體名稱，其中包含您要下載的物件、所有物件共用的物件字首，以及代表要在本機系統上下載檔案的目錄[的檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件。如果名為 的目錄尚不存在，則會建立該目錄。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Download;
import com.amazonaws.services.s3.transfer.MultipleFileDownload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;

import java.io.File;
```

 **Code** 

```
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();

try {
    MultipleFileDownload xfer = xfer_mgr.downloadDirectory(
            bucket_name, key_prefix, new File(dir_path));
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java)。

## 複製物件
<a name="transfermanager-copy-object"></a>

若要將物件從一個 S3 儲存貯體複製到另一個儲存貯體，請使用 TransferManager`copy` 方法。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Copy;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
```

 **Code** 

```
System.out.println("Copying s3 object: " + from_key);
System.out.println("      from bucket: " + from_bucket);
System.out.println("     to s3 object: " + to_key);
System.out.println("        in bucket: " + to_bucket);

TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Copy xfer = xfer_mgr.copy(from_bucket, from_key, to_bucket, to_key);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrCopy.java)。

## 等待轉接完成
<a name="transfermanager-wait-for-completion"></a>

如果您的應用程式 （或執行緒） 可以在傳輸完成之前封鎖，您可以使用 [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html) 介面的 `waitForCompletion`方法封鎖，直到傳輸完成或發生例外狀況為止。

```
try {
    xfer.waitForCompletion();
} catch (AmazonServiceException e) {
    System.err.println("Amazon service error: " + e.getMessage());
    System.exit(1);
} catch (AmazonClientException e) {
    System.err.println("Amazon client error: " + e.getMessage());
    System.exit(1);
} catch (InterruptedException e) {
    System.err.println("Transfer interrupted: " + e.getMessage());
    System.exit(1);
}
```

如果您在呼叫 *之前*輪詢事件`waitForCompletion`、在個別執行緒上實作輪詢機制，或使用 [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) 非同步接收進度更新，就會取得傳輸進度。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。

## 取得傳輸狀態和進度
<a name="transfermanager-get-status-and-progress"></a>

TransferManager`upload*`、 `download*`和 `copy`方法傳回的每個類別都會傳回下列其中一個類別的執行個體，視其為單一檔案或多檔案操作而定。


**​**  

| 類別 | 傳回者 | 
| --- | --- | 
|   [Copy (複製)](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Copy.html)   |   `copy`   | 
|   [下載](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Download.html)   |   `download`   | 
|   [MultipleFileDownload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileDownload.html)   |   `downloadDirectory`   | 
|   [上傳](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Upload.html)   |   `upload`   | 
|   [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html)   |   `uploadFileList`, `uploadDirectory`   | 

所有這些類別都會實作 [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html) 界面。 `Transfer`提供實用方法來取得傳輸進度、暫停或繼續傳輸，以及取得傳輸的目前或最終狀態。

**Topics**
+ [輪詢傳輸的目前進度](#transfermanager-get-progress-polling)
+ [使用 ProgressListener 取得傳輸進度](#transfermanager-progress-listener)
+ [取得子轉移進度](#transfermanager-get-subtransfer-progress)

### 輪詢傳輸的目前進度
<a name="transfermanager-get-progress-polling"></a>

此迴圈會列印傳輸的進度、在執行時檢查其目前的進度，並在完成時列印其最終狀態。

 **匯入** 

```
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
```

 **Code** 

```
// print the transfer's human-readable description
System.out.println(xfer.getDescription());
// print an empty progress bar...
printProgressBar(0.0);
// update the progress bar while the xfer is ongoing.
do {
    try {
        Thread.sleep(100);
    } catch (InterruptedException e) {
        return;
    }
    // Note: so_far and total aren't used, they're just for
    // documentation purposes.
    TransferProgress progress = xfer.getProgress();
    long so_far = progress.getBytesTransferred();
    long total = progress.getTotalBytesToTransfer();
    double pct = progress.getPercentTransferred();
    eraseProgressBar();
    printProgressBar(pct);
} while (xfer.isDone() == false);
// print the final state of the transfer.
TransferState xfer_state = xfer.getState();
System.out.println(": " + xfer_state);
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。

### 使用 ProgressListener 取得傳輸進度
<a name="transfermanager-progress-listener"></a>

您可以使用 Transfer 介面的 `addProgressListener`方法，將 [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) 連接到任何[傳輸](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html)。

[ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) 只需要一個方法 `progressChanged`，它需要 [ProgressEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressEvent.html) 物件。您可以使用 物件來呼叫`getBytes`操作的總位元組數，以及呼叫 到目前為止傳輸的位元組數`getBytesTransferred`。

 **匯入** 

```
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
```

 **Code** 

```
File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Upload u = xfer_mgr.upload(bucket_name, key_name, f);
    // print an empty progress bar...
    printProgressBar(0.0);
    u.addProgressListener(new ProgressListener() {
        public void progressChanged(ProgressEvent e) {
            double pct = e.getBytesTransferred() * 100.0 / e.getBytes();
            eraseProgressBar();
            printProgressBar(pct);
        }
    });
    // block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(u);
    // print the final state of the transfer.
    TransferState xfer_state = u.getState();
    System.out.println(": " + xfer_state);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。

### 取得子轉移進度
<a name="transfermanager-get-subtransfer-progress"></a>

[MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) 類別可以透過呼叫其`getSubTransfers`方法傳回其子傳輸的相關資訊。它會傳回無法修改的[上傳](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Upload.html)物件[集合](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Collection.html)，提供每個子傳輸的個別傳輸狀態和進度。

 **匯入** 

```
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
```

 **Code** 

```
Collection<? extends Upload> sub_xfers = new ArrayList<Upload>();
sub_xfers = multi_upload.getSubTransfers();

do {
    System.out.println("\nSubtransfer progress:\n");
    for (Upload u : sub_xfers) {
        System.out.println("  " + u.getDescription());
        if (u.isDone()) {
            TransferState xfer_state = u.getState();
            System.out.println("  " + xfer_state);
        } else {
            TransferProgress progress = u.getProgress();
            double pct = progress.getPercentTransferred();
            printProgressBar(pct);
            System.out.println();
        }
    }

    // wait a bit before the next update.
    try {
        Thread.sleep(200);
    } catch (InterruptedException e) {
        return;
    }
} while (multi_upload.isDone() == false);
// print the final state of the transfer.
TransferState xfer_state = multi_upload.getState();
System.out.println("\nMultipleFileUpload " + xfer_state);
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。

## 詳細資訊
<a name="transfermanager-see-also"></a>
+  Amazon Simple Storage Service 《 使用者指南》中的[物件金鑰](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html) 

# 將 Amazon S3 儲存貯體設定為網站
<a name="examples-s3-website-configuration"></a>

您可以設定 儲存 Amazon S3 貯體做為網站運作。若要這樣做，您需要設定其網站組態。

**注意**  
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。

## 設定儲存貯體的網站組態
<a name="set-a-bucket-s-website-configuration"></a>

若要設定儲存 Amazon S3 貯體的網站組態，請使用儲存貯體名稱呼叫 AmazonS3 的 `setWebsiteConfiguration`方法來設定組態，以及包含儲存貯體網站組態的 [BucketWebsiteConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/BucketWebsiteConfiguration.html) 物件。

*需要*設定索引文件；所有其他參數都是選用的。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.BucketWebsiteConfiguration;
```

 **Code** 

```
    String bucket_name, String index_doc, String error_doc) {
BucketWebsiteConfiguration website_config = null;

if (index_doc == null) {
    website_config = new BucketWebsiteConfiguration();
} else if (error_doc == null) {
    website_config = new BucketWebsiteConfiguration(index_doc);
} else {
    website_config = new BucketWebsiteConfiguration(index_doc, error_doc);
}

final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    s3.setBucketWebsiteConfiguration(bucket_name, website_config);
} catch (AmazonServiceException e) {
    System.out.format(
            "Failed to set website configuration for bucket '%s'!\n",
            bucket_name);
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
```

**注意**  
設定網站組態不會修改儲存貯體的存取許可。若要在 Web 上顯示您的檔案，您還需要設定儲存*貯體政策*，允許公開讀取儲存貯體中的檔案。如需詳細資訊，請參閱[使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取](examples-s3-bucket-policies.md)。

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetWebsiteConfiguration.java)。

## 取得儲存貯體的網站組態
<a name="get-a-bucket-s-website-configuration"></a>

若要取得儲存 Amazon S3 貯體的網站組態，請呼叫 AmazonS3 的 `getWebsiteConfiguration`方法，並指定儲存貯體的名稱來擷取其組態。

組態會以 [BucketWebsiteConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/BucketWebsiteConfiguration.html) 物件傳回。如果儲存貯體沒有網站組態，`null`則會傳回 。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.BucketWebsiteConfiguration;
```

 **Code** 

```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    BucketWebsiteConfiguration config =
            s3.getBucketWebsiteConfiguration(bucket_name);
    if (config == null) {
        System.out.println("No website configuration found!");
    } else {
        System.out.format("Index document: %s\n",
                config.getIndexDocumentSuffix());
        System.out.format("Error document: %s\n",
                config.getErrorDocument());
    }
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.out.println("Failed to get website configuration!");
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetWebsiteConfiguration.java)。

## 刪除儲存貯體的網站組態
<a name="delete-a-bucket-s-website-configuration"></a>

若要刪除儲存 Amazon S3 貯體的網站組態，請使用儲存貯體的名稱呼叫 AmazonS3 的 `deleteWebsiteConfiguration`方法，從中刪除組態。

 **匯入** 

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
```

 **Code** 

```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
    s3.deleteBucketWebsiteConfiguration(bucket_name);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.out.println("Failed to delete website configuration!");
    System.exit(1);
}
```

請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteWebsiteConfiguration.java)。

## 詳細資訊
<a name="more-information"></a>
+  Amazon S3 API 參考中的 [PUT 儲存貯體網站](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTwebsite.html) 
+  Amazon S3 API 參考中的 [GET 儲存貯體網站](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETwebsite.html) 
+  Amazon S3 API 參考中的 [DELETE 儲存貯體網站](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketDELETEwebsite.html) 

# 使用 Amazon S3 用戶端加密
<a name="examples-crypto"></a>

使用加密用戶端 Amazon S3 加密資料是您可以為存放在其中的敏感資訊提供額外一層保護的方式之一 Amazon S3。本節中的範例示範如何為您的應用程式建立和設定 Amazon S3 加密用戶端。

如果您是初次使用密碼編譯，請參閱 AWS KMS 開發人員指南中的[密碼編譯基本概念](https://docs.aws.amazon.com/kms/latest/developerguide/crypto-intro.html)，以取得密碼編譯術語和演算法的基本概觀。如需有關跨 AWS SDKs加密支援的資訊，請參閱《 Amazon Web Services 一般參考》中的[AWSAmazon S3 用戶端加密的 SDK 支援](https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html)。

**注意**  
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。

如果您使用的是 1.11.836 版或更早的版本 適用於 Java 的 AWS SDK，請參閱[Amazon S3 加密用戶端遷移](s3-encryption-migration.md)，以取得將應用程式遷移至更新版本的相關資訊。如果您無法遷移，請參閱 GitHub 上的[此完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java)。

否則，如果您使用的是 1.11.837 版或更新版本 適用於 Java 的 AWS SDK，請探索下列範例主題，以使用 Amazon S3 用戶端加密。

**Topics**
+ [Amazon S3 使用用戶端主金鑰的用戶端加密](examples-crypto-masterkey.md)
+ [Amazon S3 使用 AWS KMS 受管金鑰的用戶端加密](examples-crypto-kms.md)

# Amazon S3 使用用戶端主金鑰的用戶端加密
<a name="examples-crypto-masterkey"></a>

下列範例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 類別來建立已啟用用戶端加密的 Amazon S3 用戶端。啟用後，您 Amazon S3 使用此用戶端上傳到 的任何物件都會加密。您從 Amazon S3 使用此用戶端取得的任何物件都會自動解密。

**注意**  
下列範例示範搭配客戶受管 Amazon S3 用戶端主金鑰使用用戶端加密。若要了解如何搭配 AWS KMS 受管金鑰使用加密，請參閱搭配 [Amazon S3AWS KMS 受管金鑰的用戶端加密](examples-crypto-kms.md)。

啟用用戶端加密時，您可以選擇兩種 Amazon S3 加密模式：嚴格驗證或驗證。下列各節說明如何啟用每種類型。若要了解每個模式使用哪些演算法，請參閱 [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html) 定義。

## 必要的匯入
<a name="required-imports"></a>

匯入下列類別以取得這些範例。

 **匯入** 

```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
import com.amazonaws.services.s3.model.CryptoMode;
import com.amazonaws.services.s3.model.EncryptionMaterials;
import com.amazonaws.services.s3.model.StaticEncryptionMaterialsProvider;
```

## 嚴格驗證加密
<a name="strict-authenticated-encryption"></a>

如果`CryptoMode`未指定 ，嚴格驗證加密是預設模式。

若要明確啟用此模式，請在 `withCryptoConfiguration`方法中指定 `StrictAuthenticatedEncryption`值。

**注意**  
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。

 **Code** 

```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
         .withRegion(Regions.US_WEST_2)
         .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
         .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
         .build();

s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt");
```

## 已驗證的加密模式
<a name="authenticated-encryption-mode"></a>

當您使用 `AuthenticatedEncryption` 模式時，會在加密期間套用改進的金鑰包裝演算法。在此模式下解密時，演算法可以驗證解密物件的完整性，並在檢查失敗時擲回例外狀況。如需驗證加密運作方式的詳細資訊，請參閱[Amazon S3 用戶端驗證加密](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)部落格文章。

**注意**  
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。

若要啟用此模式，請在 `withCryptoConfiguration`方法中指定 `AuthenticatedEncryption`值。

 **Code** 

```
AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard()
         .withRegion(Regions.DEFAULT_REGION)
         .withClientConfiguration(new ClientConfiguration())
         .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption))
         .withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
         .build();

s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt");
```

# Amazon S3 使用 AWS KMS 受管金鑰的用戶端加密
<a name="examples-crypto-kms"></a>

下列範例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 類別來建立已啟用用戶端加密的 Amazon S3 用戶端。設定完成後，任何使用此用戶端上傳到 Amazon S3 的物件都會加密。您從 Amazon S3 使用此用戶端取得的任何物件都會自動解密。

**注意**  
下列範例示範如何搭配 AWS KMS 受管金鑰使用 Amazon S3 用戶端加密。若要了解如何使用加密搭配您自己的金鑰，請參閱[Amazon S3 用戶端加密搭配用戶端主金鑰](examples-crypto-masterkey.md)。

啟用用戶端加密時，您可以選擇兩種 Amazon S3 加密模式：嚴格驗證或驗證。下列各節說明如何啟用每種類型。若要了解每個模式使用哪些演算法，請參閱 [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html) 定義。

## 必要的匯入
<a name="required-imports"></a>

匯入下列類別以取得這些範例。

 **匯入** 

```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.kms.AWSKMS;
import com.amazonaws.services.kms.AWSKMSClientBuilder;
import com.amazonaws.services.kms.model.GenerateDataKeyRequest;
import com.amazonaws.services.kms.model.GenerateDataKeyResult;
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
import com.amazonaws.services.s3.model.CryptoMode;
import com.amazonaws.services.s3.model.EncryptionMaterials;
import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider;
```

## 嚴格驗證加密
<a name="strict-authenticated-encryption-kms"></a>

如果`CryptoMode`未指定 ，嚴格驗證加密是預設模式。

若要明確啟用此模式，請在 `withCryptoConfiguration`方法中指定 `StrictAuthenticatedEncryption`值。

**注意**  
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。

 **Code** 

```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
         .withRegion(Regions.US_WEST_2)
         .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
         .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
         .build();

s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```

在 Amazon S3 加密用戶端上呼叫 `putObject`方法以上傳物件。

 **Code** 

```
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
```

您可以使用相同的用戶端擷取物件。此範例會呼叫 `getObjectAsString`方法，以擷取存放的字串。

 **Code** 

```
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```

## 已驗證的加密模式
<a name="authenticated-encryption-kms"></a>

當您使用 `AuthenticatedEncryption` 模式時，會在加密期間套用改進的金鑰包裝演算法。在此模式下解密時，演算法可以驗證解密物件的完整性，並在檢查失敗時擲回例外狀況。如需驗證加密運作方式的詳細資訊，請參閱[Amazon S3 用戶端驗證加密](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)部落格文章。

**注意**  
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。

若要啟用此模式，請在 `withCryptoConfiguration`方法中指定 `AuthenticatedEncryption`值。

 **Code** 

```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
         .withRegion(Regions.US_WEST_2)
         .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
         .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
         .build();
```

## 設定 AWS KMS 用戶端
<a name="configure-kms"></a>

除非明確指定，否則 Amazon S3 加密用戶端預設會建立 AWS KMS 用戶端。

若要為此自動建立的 AWS KMS 用戶端設定區域，請設定 `awsKmsRegion`。

 **Code** 

```
Region kmsRegion = Region.getRegion(Regions.AP_NORTHEAST_1);

AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
        .withRegion(Regions.US_WEST_2)
        .withCryptoConfiguration(new CryptoConfigurationV2().withAwsKmsRegion(kmsRegion))
        .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
        .build();
```

或者，您可以使用自己的 AWS KMS 用戶端來初始化加密用戶端。

 **Code** 

```
AWSKMS kmsClient = AWSKMSClientBuilder.standard()
        .withRegion(Regions.US_WEST_2);
        .build();

AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
        .withRegion(Regions.US_WEST_2)
        .withKmsClient(kmsClient)
        .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
        .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
        .build();
```