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

# 使用高效能 S3 用戶端： AWS CRT 型 S3 用戶端
<a name="crt-based-s3-client"></a>

 AWS CRT 型 S3 用戶端，建置在[AWS 通用執行期 (CRT)](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html) 之上，是替代的 S3 非同步用戶端。它會自動使用 Amazon S3 的[分段上傳 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 和[位元組範圍擷取](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance-guidelines.html#optimizing-performance-guidelines-get-range)，以增強的效能和可靠性在 Amazon S3) 之間來回傳輸物件。

 AWS CRT 型 S3 用戶端可在發生網路故障時改善傳輸可靠性。透過重試檔案傳輸的個別失敗部分，而不從頭重新開始傳輸，可改善可靠性。

此外，以 AWS CRT 為基礎的 S3 用戶端提供增強型連線集區和網域名稱系統 (DNS) 負載平衡，也可改善輸送量。

您可以使用 AWS CRT 型 S3 用戶端取代 SDK 的標準 S3 非同步用戶端，並立即利用其改善的輸送量。

**重要**  
 AWS CRT 型 S3 用戶端目前不支援用戶端層級或請求層級的 [SDK 指標集合](metrics.md)。

**AWS 開發套件中的 CRT 型元件**

本主題中所述的 AWS CRT 型* S3* 用戶端和 AWS CRT 型 *HTTP* 用戶端是 SDK 中的不同元件。

**AWS CRT 型 S3 用戶端**是 [S3AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) 界面的實作，用於使用 Amazon S3 服務。這是以 Java 為基礎的`S3AsyncClient`介面實作的替代方案，並提供多種優點。

[AWS CRT 型 HTTP 用戶端](http-configuration-crt.md)是 [SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html) 界面的實作，用於一般 HTTP 通訊。這是`SdkAsyncHttpClient`介面 Netty 實作的替代方案，並提供數種優點。

雖然這兩個元件都使用[AWS 通用執行期](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)的程式庫，但以 AWS CRT 為基礎的 S3 用戶端會使用 [aws-c-s3 程式庫](https://github.com/awslabs/aws-c-s3)，並支援 [S3 分段上傳 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 功能。由於 AWS CRT 型 HTTP 用戶端適用於一般用途，因此不支援 S3 分段上傳 API 功能。

## 新增相依性以使用 AWS CRT 型 S3 用戶端
<a name="crt-based-s3-client-depend"></a>

若要使用 AWS CRT 型 S3 用戶端，請將下列兩個相依性新增至 Maven 專案檔案。此範例顯示要使用的最低版本。搜尋 Maven 中央儲存庫以取得最新版本的 [s3](https://central.sonatype.com/artifact/software.amazon.awssdk/s3) 和 [aws-crt](https://central.sonatype.com/artifact/software.amazon.awssdk.crt/aws-crt) 成品。

```
<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>s3</artifactId>
  <version>2.27.21</version>
</dependency>
<dependency>
  <groupId>software.amazon.awssdk.crt</groupId>
  <artifactId>aws-crt</artifactId>
  <version>0.30.11</version>
</dependency>
```

## 建立 AWS CRT 型 S3 用戶端的執行個體
<a name="crt-based-s3-client-create"></a>

 使用預設設定建立 AWS CRT 型 S3 用戶端的執行個體，如下列程式碼片段所示。

```
S3AsyncClient s3AsyncClient = S3AsyncClient.crtCreate();
```

若要設定用戶端，請使用 AWS CRT 用戶端建置器。您可以透過變更建置器方法，從標準 S3 非同步用戶端切換至 AWS CRT 型用戶端。

```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3AsyncClient;


S3AsyncClient s3AsyncClient = 
        S3AsyncClient.crtBuilder()
                     .credentialsProvider(DefaultCredentialsProvider.create())
                     .region(Region.US_WEST_2)
                     .targetThroughputInGbps(20.0)
                     .minimumPartSizeInBytes(8 * 1025 * 1024L)
                     .build();
```

**注意**  
 AWS CRT 用戶端建置器目前可能不支援標準建置器中的某些設定。呼叫 以取得標準建置器`S3AsyncClient#builder()`。

## 使用 AWS CRT 型 S3 用戶端
<a name="crt-based-s3-client-use"></a>

使用 AWS CRT 型 S3 用戶端呼叫 Amazon S3 API 操作。下列範例示範 [PutObject](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html#putObject(java.util.function.Consumer,software.amazon.awssdk.core.async.AsyncRequestBody)) 和 [GetObject](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html#getObject(java.util.function.Consumer,software.amazon.awssdk.core.async.AsyncResponseTransformer)) 操作可透過 取得 適用於 Java 的 AWS SDK。

```
import software.amazon.awssdk.core.async.AsyncRequestBody;
import software.amazon.awssdk.core.async.AsyncResponseTransformer;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import software.amazon.awssdk.services.s3.model.PutObjectResponse;


S3AsyncClient s3Client = S3AsyncClient.crtCreate();

// Upload a local file to Amazon S3.
PutObjectResponse putObjectResponse = 
      s3Client.putObject(req -> req.bucket(<BUCKET_NAME>)
                                   .key(<KEY_NAME>),
                        AsyncRequestBody.fromFile(Paths.get(<FILE_NAME>)))
              .join();

// Download an object from Amazon S3 to a local file.
GetObjectResponse getObjectResponse = 
      s3Client.getObject(req -> req.bucket(<BUCKET_NAME>)
                                   .key(<KEY_NAME>),
                        AsyncResponseTransformer.toFile(Paths.get(<FILE_NAME>)))
              .join();
```

## 上傳大小不明的串流
<a name="crt-stream-unknown-size"></a>

 AWS AWS CRT 型 S3 用戶端的一個重要優點是能夠有效地處理未知大小的輸入串流。當您需要從無法事先決定總大小的來源上傳資料時，這特別有用。

```
public PutObjectResponse crtClient_stream_unknown_size(String bucketName, String key, InputStream inputStream) {

    S3AsyncClient s3AsyncClient = S3AsyncClient.crtCreate();
    ExecutorService executor = Executors.newSingleThreadExecutor();
    AsyncRequestBody body = AsyncRequestBody.fromInputStream(inputStream, null, executor);  // 'null' indicates that the
                                                                                            // content length is unknown.
    CompletableFuture<PutObjectResponse> responseFuture =
            s3AsyncClient.putObject(r -> r.bucket(bucketName).key(key), body)
                    .exceptionally(e -> {
                        if (e != null){
                            logger.error(e.getMessage(), e);
                        }
                        return null;
                    });

    PutObjectResponse response = responseFuture.join(); // Wait for the response.
    executor.shutdown();
    return response;
}
```

此功能有助於避免傳統上傳的常見問題，其中不正確的內容長度規格可能會導致截斷物件或上傳失敗。

## 組態限制
<a name="crt-based-s3-client-limitations"></a>

 AWS CRT 型 S3 用戶端和 Java 型 S3 非同步用戶端[提供可比較的功能](examples-s3.md#s3-clients)，而 AWS CRT 型 S3 用戶端提供效能邊緣。不過，以 AWS CRT 為基礎的 S3 用戶端缺少以 Java 為基礎的 S3 非同步用戶端所擁有的組態設定。這些設定包括：
+ *用戶端層級組態：*API 呼叫嘗試逾時、壓縮執行攔截器、指標發佈者、自訂執行屬性、自訂進階選項、自訂排程執行器服務、自訂標頭
+ *請求層級組態：*自訂簽署者、API 呼叫嘗試逾時

如需組態差異的完整清單，請參閱 API 參考。


| Java 型 S3 非同步用戶端 | AWS CRT 型 S3 用戶端 | 
| --- | --- | 
| 用戶端層級組態[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/crt-based-s3-client.html)請求層級組態[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/crt-based-s3-client.html) | 用戶端層級組態[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/crt-based-s3-client.html)請求層級組態[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/crt-based-s3-client.html) |