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

# 設定 AWS CRT 型 HTTP 用戶端
<a name="http-configuration-crt"></a>

 AWS CRT 型 HTTP 用戶端包含同步 [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) 和非同步 [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)。 AWS CRT 型 HTTP 用戶端提供下列 HTTP 用戶端優點：
+ 更快速的 SDK 啟動時間
+ 記憶體佔用空間較小
+ 延遲時間縮短
+ 連線運作狀態管理
+ DNS 負載平衡

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

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

同步和非同步 **AWS CRT 型 HTTP 用戶端**是 SDK HTTP 用戶端介面的實作，用於一般 HTTP 通訊。它們是 SDK 中其他同步或非同步 HTTP 用戶端的替代方案，具有其他優點。

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

雖然這兩個元件都使用[AWS 通用執行期](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)的程式庫，但以 AWS CRT 為基礎的 HTTP 用戶端不會使用 [aws-c-s3 程式庫](https://github.com/awslabs/aws-c-s3)，也不支援 [S3 分段上傳 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 功能。相較之下， AWS CRT 型 S3 用戶端是專為支援 S3 分段上傳 API 功能而打造。

## 存取 AWS CRT 型 HTTP 用戶端
<a name="http-config-crt-access"></a>

在使用 AWS CRT 型 HTTP 用戶端之前，請先將最低版本為 2.22.0 的`aws-crt-client`成品新增至專案的相依性。

使用下列其中一個選項來設定 Maven `pom.xml` 檔案。

**注意**  
 如果您需要將執行時間相依性的大小縮小，例如，如果您的應用程式在 AWS Lambda 函數中執行，您可以選擇使用*平台特定的 jar 選項*。

------
#### [ Uber-jar option ]

根據預設， `aws-crt-client`會使用 uber-jar 的 AWS CRT 成品，其中包含多個平台的二進位檔，包括 Linux、Windows 和 macOS。

```
<project>
   <properties>
     <aws.sdk.java.version>2.29.10*</aws.sdk.java.version>
  </properties>
  <dependencyManagement>
   <dependencies>
      <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bom</artifactId>
        <version>${aws.sdk.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
   </dependencies>
  </dependencyManagement>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>aws-crt-client</artifactId>
   </dependency>
  </dependencies>
</project>
```

\$1將紅色顯示的版本取代為您要使用的 Java 開發套件版本。尋找 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 的最新資訊。

------
#### [ Platform-specific jar option ]

若要將 Java 執行時間限制為 AWS CRT 程式庫的平台特定版本，請對 *Uber-jar 選項*進行下列變更。
+ 將 `exclusions`元素新增至 SDK 的`aws-crt-client`成品。此排除可防止 SDK 暫時使用 AWS CRT uber-jar。
+ 為您需要的特定 AWS CRT 平台版本新增相依性元素。請參閱以下步驟**以判斷 AWS CRT 成品版本**，了解如何判斷正確的版本。

```
<project>
   <properties>
     <aws.sdk.java.version>2.29.101</aws.sdk.java.version>
  </properties>
   <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>software.amazon.awssdk</groupId>
                <artifactId>bom</artifactId>
                <version>${aws.sdk.java.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>aws-crt-client</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>software.amazon.awssdk.crt</groupId>
                    <artifactId>aws-crt</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.31.32</version>
            <classifier>linux-x86_643</classifier>
        </dependency>
    </dependencies>
```

1將紅色顯示的版本取代為您要使用的 Java 開發套件版本。尋找 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 的最新資訊。

2取代由 *Uber-jar 選項*`software.amazon.awssdk.crt:aws-crt`提供的 版本。請參閱**下列步驟以判斷 AWS CRT 成品版本**。

3將 `classifier`值取代為您的平台。如需[可用值的清單](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars)，請參閱適用於 Java 的 AWS CRT GitHub 頁面。

**判斷 AWS CRT 成品版本的步驟**

使用下列步驟來判斷與您所使用的適用於 Java 的 開發套件版本相容的 AWS CRT 成品版本。

1. 如 *Uber-jar 選項*所示設定您的`pom.xml`檔案。此設定可讓您查看軟體`software.amazon.awssdk.crt:aws-crt`開發套件預設導入的版本。

1. 在專案的根目錄 （與 `pom.xml` 檔案位於相同的目錄中），執行下列 Maven 命令：

   ```
   mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt
   ```

   Maven 可能會執行其他動作，但最終您應該會看到 SDK 暫時使用的`software.amazon.awssdk.crt:aws-crt`相依性的主控台輸出。下列程式碼片段顯示以 開發套件版本為基礎的範例輸出`2.29.10`：

   ```
   [INFO] org.example:yourProject:jar:1.0-SNAPSHOT
   [INFO] \- software.amazon.awssdk:aws-crt-client:jar:2.29.10:compile
   [INFO]    \- software.amazon.awssdk.crt:aws-crt:jar:0.31.3:compile
   ```

1. 使用主控台為`software.amazon.awssdk.crt:aws-crt`成品顯示的版本。在此情況下，請將 `0.31.3`新增至您的 `pom.xml` 檔案。

------

## 使用和設定 AWS CRT 型 HTTP 用戶端
<a name="http-crt-config"></a>

您可以設定以 AWS CRT 為基礎的 HTTP 用戶端，以及建置服務用戶端，也可以設定單一執行個體在多個服務用戶端之間共用。

使用任一種方法，您可以使用建置器來[設定 CRT 型 HTTP 用戶端執行個體的屬性](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html)。 AWS 

### 最佳實務：將執行個體專用於服務用戶端
<a name="http-config-crt-one-client"></a>

如果您需要設定 AWS CRT 型 HTTP 用戶端的執行個體，建議您將它與服務用戶端一起建置，以專用執行個體。您可以使用服務用戶端建置器的 `httpClientBuilder`方法來執行此操作。如此一來，HTTP 用戶端的生命週期由 SDK 管理，如果不再需要以 AWS CRT 為基礎的 HTTP 用戶端執行個體，則有助於避免潛在的記憶體流失。

下列範例會建立 S3 服務用戶端，並使用 `connectionTimeout`和 `maxConcurrency`值設定 AWS CRT 型 HTTP 用戶端。

------
#### [ Synchronous client ]

**匯入**

```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```

**Code**

```
// Singleton: Use s3Client for all requests.
S3Client s3Client = S3Client.builder()
    .httpClientBuilder(AwsCrtHttpClient
        .builder()
        .connectionTimeout(Duration.ofSeconds(3))
        .maxConcurrency(100))
    .build();

// Perform work with the s3Client.

// Requests completed: Close the s3Client.
s3Client.close();
```

------
#### [ Asynchronous client ]

**匯入**

```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```

**Code**

```
// Singleton: Use s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClientBuilder(AwsCrtAsyncHttpClient
        .builder()
        .connectionTimeout(Duration.ofSeconds(3))
        .maxConcurrency(100))
    .build();

// Perform work with the s3AsyncClient.

// Requests completed: Close the s3AsyncClient.
s3AsyncClient.close();
```

------

### 替代方法：共用執行個體
<a name="http-config-crt-multi-clients"></a>

為了協助降低應用程式的資源和記憶體用量，您可以設定 AWS CRT 型 HTTP 用戶端，並在多個服務用戶端之間共用。HTTP 連線集區將共用，這會降低資源用量。

**注意**  
共用 AWS CRT 型 HTTP 用戶端執行個體時，您必須在準備好進行處置時將其關閉。當服務用戶端關閉時，軟體開發套件不會關閉執行個體。

下列範例會使用 `connectionTimeout`和 `maxConcurrency`值設定 AWS CRT 型 HTTP 用戶端執行個體。設定的執行個體會傳遞至每個服務用戶端建置器的 `httpClient`方法。當不再需要服務用戶端和 HTTP 用戶端時，它們會明確關閉。HTTP 用戶端最後會關閉。

------
#### [ Synchronous client ]

**匯入**

```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```

**Code**

```
// Create an AwsCrtHttpClient shared instance.
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(3))
    .maxConcurrency(100)
    .build();

// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client = S3Client.builder()
    .httpClient(crtHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.crea
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
    .httpClient(crtHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.crea
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
crtHttpClient.close();  // Explicitly close crtHttpClient.
```

------
#### [ Asynchronous client ]

**匯入**

```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```

**Code**

```
// Create an AwsCrtAsyncHttpClient shared instance.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(3))
    .maxConcurrency(100)
    .build();

// Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClient(crtAsyncHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder()
    .httpClient(crtAsyncHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

// Requests completed: Close all service clients.
s3AsyncClient.close();
dynamoDbAsyncClient.close();
crtAsyncHttpClient.close();  // Explicitly close crtAsyncHttpClient.
```

------

## 將 AWS CRT 型 HTTP 用戶端設定為預設值
<a name="setting-the-crt-based-http-client-as-the-default"></a>

您可以設定 Maven 建置檔案，讓 SDK 使用 AWS CRT 型 HTTP 用戶端做為服務用戶端的預設 HTTP 用戶端。

您可以透過將具有預設 HTTP 用戶端相依性的 `exclusions`元素新增至每個服務用戶端成品來執行此操作。

在下列`pom.xml`範例中，軟體開發套件使用適用於 S3 服務的 AWS CRT 型 HTTP 用戶端。如果程式碼中的服務用戶端是 `S3AsyncClient`，則 SDK 會使用 `AwsCrtAsyncHttpClient`。如果服務用戶端是 S3Client，則 SDK 會使用 `AwsCrtHttpClient`。透過此設定，預設 Netty 型非同步 HTTP 用戶端和預設 Apache 型同步 HTTP 無法使用。

```
<project>
   <properties>
     <aws.sdk.version>VERSION</aws.sdk.version>
  </properties>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>s3</artifactId>
      <version>${aws.sdk.version}</version>
      <exclusions>
         <exclusion>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>netty-nio-client</artifactId>
         </exclusion>
         <exclusion>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>apache-client</artifactId>
         </exclusion>
      </exclusions>
   </dependency>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>aws-crt-client</artifactId>
   </dependency>
  </dependencies>
</project>
```

請造訪 Maven 中央儲存庫以取得最新的 [https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 值。

**注意**  
如果在`pom.xml`檔案中宣告多個服務用戶端，則所有 都需要 `exclusions` XML 元素。

### 使用 Java 系統屬性
<a name="setting-via-java-system-property"></a>

若要使用 AWS CRT 型 HTTP 用戶端做為應用程式的預設 HTTP，您可以將 Java 系統屬性`software.amazon.awssdk.http.async.service.impl`設定為 的值`software.amazon.awssdk.http.crt.AwsCrtSdkHttpService`。

若要在應用程式啟動期間設定 ，請執行類似以下的命令。

```
java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\
software.amazon.awssdk.http.crt.AwsCrtSdkHttpService
```

使用下列程式碼片段，在您的應用程式程式碼中設定系統屬性。

```
System.setProperty("software.amazon.awssdk.http.async.service.impl",
"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");
```

**注意**  
當您使用系統屬性來設定 AWS CRT 型 HTTP 用戶端的使用時，您需要在`poml.xml`檔案中的`aws-crt-client`成品上新增相依性。

## AWS CRT 型 HTTP 用戶端的進階組態
<a name="configuring-the-crt-based-http-client"></a>

您可以使用 AWS CRT 型 HTTP 用戶端的各種組態設定，包括連線運作狀態組態和閒置時間上限。您可以檢閱 [可用的組態選項](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html)`AwsCrtAsyncHttpClient`。您可以為 設定相同的選項`AwsCrtHttpClient`。

### 連線運作狀態組態
<a name="connection-health-checks"></a>

您可以使用 HTTP 用戶端建置器上的 `connectionHealthConfiguration`方法，設定 AWS CRT 型 HTTP 用戶端的連線運作狀態組態。

下列範例會建立 S3 服務用戶端，該用戶端使用以連線運作狀態組態設定的 AWS CRT 型 HTTP 用戶端執行個體，以及連線的閒置時間上限。

------
#### [ Synchronous client ]

**匯入**

```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```

**Code**

```
// Singleton: Use the s3Client for all requests.
S3Client s3Client = S3Client.builder()
    .httpClientBuilder(AwsCrtHttpClient
        .builder()
        .connectionHealthConfiguration(builder -> builder
            .minimumThroughputInBps(32000L)
            .minimumThroughputTimeout(Duration.ofSeconds(3)))
        .connectionMaxIdleTime(Duration.ofSeconds(5)))
    .build();

// Perform work with s3Client.

// Requests complete: Close the service client.
s3Client.close();
```

------
#### [ Asynchronous client ]

**匯入**

```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```

**Code**

```
// Singleton: Use the s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClientBuilder(AwsCrtAsyncHttpClient
        .builder()
        .connectionHealthConfiguration(builder -> builder
            .minimumThroughputInBps(32000L)
            .minimumThroughputTimeout(Duration.ofSeconds(3)))
        .connectionMaxIdleTime(Duration.ofSeconds(5)))
    .build();

// Perform work with s3AsyncClient.

// Requests complete: Close the service client.
s3AsyncClient.close();
```

------

## HTTP/2 支援
<a name="limitation-the-crt-based-http-client"></a>

 AWS CRT 型 HTTP 用戶端尚未支援 HTTP/2 通訊協定，但計劃在未來發行。

同時，如果您使用的是需要 HTTP/2 支援的服務用戶端，例如 [KinesisAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html) 或 [TranscribeStreamingAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/transcribestreaming/TranscribeStreamingAsyncClient.html)，請考慮改用 [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)。

## Proxy 組態範例
<a name="http-config-crt-proxy-ex"></a>

下列程式碼片段顯示[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html)您使用 來設定程式碼中的代理設定。

------
#### [ Synchronous client ]

**匯入**

```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```

**Code**

```
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .host("myproxy")
        .port(1234)
        .username("username")
        .password("password")
        .nonProxyHosts(Set.of("localhost", "host.example.com"))
        .build())
    .build();
```

------
#### [ Asynchronous client ]

**匯入**

```
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```

**Code**

```
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .host("myproxy")
        .port(1234)
        .username("username")
        .password("password")
        .nonProxyHosts(Set.of("localhost", "host.example.com"))
        .build())
    .build();
```

------

代理組態的同等 Java 系統屬性會顯示在下列命令列程式碼片段中。

```
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```

**重要**  
若要使用任何 HTTPS 代理系統屬性， `scheme` 屬性必須在程式碼中設定為 `https`。如果未在程式碼中設定結構描述屬性，則結構描述預設為 HTTP，開發套件只會尋找`http.*`系統屬性。

使用環境變數的同等設定為：

```
// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"

// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .useSystemPropertyValues(Boolean.FALSE)
        .build())
    .build();

// Run the application.
// $ java -cp ... App
```