本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 配置 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 SDK 中基于 CRT 的组件**

本主题中介绍 AWS 的基于 CRT 的 *HTTP* 客户端和 AWS 基于 CRT 的 *S3* 客户端是软件开发工具包中的不同组件。

同步和异步**基于AWS CRT 的 HTTP 客户端**是 SDK HTTP 客户端接口的实现，用于一般 HTTP 通信。它们是 SDK 中其他同步或异步 HTTP 客户端的替代方案，提供额外优点。

**[AWS 基于 CRT 的 S3 客户端](crt-based-s3-client.md)**是 S [3 AsyncClient](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` 文件。

**注意**  
 如果您需要缩小运行时依赖项的大小（例如，如果您的应用程序在函数中运行），则可以选择使用*平台特定的 jar 选项*。 AWS Lambda 

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

默认情况下，`aws-crt-client`使用一大堆 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 SDK 版本。在 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 上查找最新版本。

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

*要将 Java 运行时限制为特定平台版本的 AWS CRT 库，请对 Uber-JAR 选项进行以下更改。*
+ 向 SDK 的 `aws-crt-client` 构件添加一个 `exclusions` 元素。此排除会阻止 SDK 以传递方式使用 C AWS RT 超级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 SDK 版本。在 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 上查找最新版本。

2替换*全能 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 的 SDK 版本兼容的 AWS CRT 构件版本。

1. 按照*全能 JAR 包选项*所示设置您的 `pom.xml` 文件。借助此设置，您可以查看默认情况下 SDK 会引入什么版本的 `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` 依赖项的控制台输出。以下代码段显示了基于 SDK 版本 `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 客户端，也可以将单个实例配置为在多个服务客户端之间共享。

无论采用哪种方法，您都可以使用生成器来[配置 AWS 基于 CRT 的 HTTP 客户端实例的属性](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html)。

### 最佳实践：将一个实例专用于一个服务客户端
<a name="http-config-crt-one-client"></a>

如果您需要配置 AWS 基于 CRT 的 HTTP 客户端的实例，我们建议您将该实例与服务客户端一起构建，从而将其专用。您可以通过使用服务客户端生成器的 `httpClientBuilder` 方法来执行此操作。这样，HTTP 客户端的生命周期就由 SDK 管理，这有助于避免在不再需要 AWS 基于 CRT 的 HTTP 客户端实例时未关闭时可能发生的内存泄漏。

以下示例创建一个 S3 服务客户端，并使用和值配置 AWS 基于 CRT 的 HTTP 客户端`connectionTimeout`。`maxConcurrency`

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

**导入**

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

**代码**

```
// 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;
```

**代码**

```
// 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 客户端实例时，您必须在准备好处置时将其关闭。服务客户端关闭后，SDK 不会关闭实例。

以下示例使用`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;
```

**代码**

```
// 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;
```

**代码**

```
// 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`示例中，软件开发工具包将 AWS 基于 CRT 的 HTTP 客户端用于 S3 服务。如果您的代码中的服务客户端是 `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 客户端的各种配置设置，包括连接运行状况配置和最大空闲时间。您可以查看适用于 `AwsCrtAsyncHttpClient` 的[可用配置选项](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html)。您可以为 `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;
```

**代码**

```
// 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;
```

**代码**

```
// 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)

## 代理配置示例
<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;
```

**代码**

```
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;
```

**代码**

```
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`。如果未在代码中设置 scheme 属性，则架构默认为 HTTP，SDK 仅查找 `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
```