Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅
中国的 Amazon Web Services 服务入门
(PDF)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
配置基于 Amazon CRT 的 HTTP 客户端
基于 Amazon CRT 的 HTTP 客户端包括同步 AwsCrtHttpClient 和异步 AwsCrtAsyncHttpClient。基于 Amazon CRT 的 HTTP 客户端具有以下 HTTP 客户端优势:
-
更快的 SDK 启动时间
-
更小的内存占用空间
-
降低的延迟时间
-
连接运行状况管理
-
DNS 负载均衡
SDK 中基于 Amazon CRT 的组件
本主题中介绍的基于 Amazon CRT 的 HTTP 客户端,与基于 Amazon CRT 的 S3 客户端是 SDK 中的不同组件。
同步和异步基于 Amazon CRT 的 HTTP 客户端是 SDK HTTP 客户端接口的实现,用于一般 HTTP 通信。它们是 SDK 中其他同步或异步 HTTP 客户端的替代方案,提供额外优点。
基于 Amazon CRT 的 S3 客户端是 S3AsyncClient 接口的实现,用于与 Amazon S3 服务配合使用。它是基于 Java 的 S3AsyncClient
接口实现的替代方案,具有多种优点。
尽管两个组件都使用 Amazon 通用运行时系统中的库,但基于 Amazon CRT 的 HTTP 客户端不使用 aws-c-s3 库,也不支持 S3 分段上传 API 功能。相比之下,基于 Amazon CRT 的 S3 客户端是专为支持 S3 分段上传 API 功能而构建的。
访问基于 Amazon CRT 的 HTTP 客户端
在使用基于 Amazon CRT 的 HTTP 客户端之前,请先将版本最低为 2.22.0 的 aws-crt-client
构件添加到项目的依赖项中。
以下 Maven pom.xml
显示了使用材料清单(BOM)机制声明的基于 Amazon CRT 的 HTTP 客户端。
<project>
<properties>
<aws.sdk.version>2.22.0
</aws.sdk.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>
访问 Maven Central 存储库以获取最新版本。
使用和配置基于 Amazon CRT 的 HTTP 客户端
您可以在生成服务客户端的同时配置一个基于 Amazon CRT 的 HTTP 客户端,也可以将单个实例配置为在多个服务客户端之间共享。
无论哪种方法,您都可以使用生成器为基于 Amazon CRT 的 HTTP 客户端实例配置属性。
最佳实践:将一个实例专用于一个服务客户端
如果您需要配置基于 Amazon CRT 的 HTTP 客户端的实例,我们建议您与服务客户端一同构建,从而将实例专用。您可以通过使用服务客户端生成器的 httpClientBuilder
方法来执行此操作。这样,HTTP 客户端的生命周期就由 SDK 管理,这有助于避免在不再需要基于 Amazon CRT 的 HTTP 客户端实例却不关闭实例时可能发生的内存泄漏。
以下示例创建 S3 服务客户端,并使用 connectionTimeout
和 maxConcurrency
值配置基于 Amazon CRT 的 HTTP 客户端。
- 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();
替代方法:共享 实例
为了帮助降低应用程序的资源和内存使用量,您可以配置一个基于 Amazon CRT 的 HTTP 客户端,并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池,从而降低资源使用量。
共享基于 Amazon CRT 的 HTTP 客户端实例时,必须在准备好弃置实例时将其关闭。服务客户端关闭后,SDK 不会关闭实例。
以下示例使用 connectionTimeout
和 maxConcurrency
值配置基于 Amazon 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.
将基于 Amazon CRT 的 HTTP 客户端设置为默认客户端
您可以设置 Maven 构建文件,让 SDK 使用基于 Amazon CRT 的 HTTP 客户端作为服务客户端的默认 HTTP 客户端。
为此,您可以向每个服务客户端构件添加一个具有默认 HTTP 客户端依赖项的 exclusions
元素。
在以下 pom.xml
示例中,SDK 将基于 Amazon 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 Central 存储库以获取最新的 VERSION
值。
如果在一个 pom.xml
文件中声明了多个服务客户端,则所有服务客户端都需要 exclusions
XML 元素。
使用 Java 系统属性
要使用基于 Amazon 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");
当您使用系统属性配置基于 Amazon CRT 的 HTTP 客户端的使用时,需要在 poml.xml
文件中向 aws-crt-client
构件添加依赖项。
基于 Amazon CRT 的 HTTP 客户端的高级配置
您可以使用基于 Amazon CRT 的 HTTP 客户端的各种配置设置,包括连接运行状况配置和最大空闲时间。您可以查看适用于 AwsCrtAsyncHttpClient
的可用配置选项。您可以为 AwsCrtHttpClient
配置相同的选项。
连接运行状况配置
您可以使用 HTTP 客户端生成器上的 connectionHealthConfiguration
方法为基于 Amazon CRT 的 HTTP 客户端配置连接运行状况配置。
以下示例创建了一个 S3 服务客户端,该客户端使用基于 Amazon 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 支持
基于 Amazon CRT 的 HTTP 客户端尚不支持 HTTP/2 协议,但计划在将来的版本中推出该支持。
在现阶段,如果您使用的是需要 HTTP/2 支持的服务客户端,例如 KinesisAsyncClient 或 TranscribeStreamingAsyncClient,可以考虑改用 NettyNioAsyncHttpClient。
代理配置示例
以下代码段显示了如何使用 ProxyConfiguration.Builder
在代码中配置代理设置。
- 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")
.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")
.build())
.build();
以下命令行片段显示了代理配置的等效 Java 系统属性。
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -cp ... App
要使用任何 HTTPS 代理系统属性,必须在代码中将 scheme
属性设置为 https
。如果未在代码中设置 scheme 属性,则架构默认为 HTTP,SDK 仅查找 http.*
系统属性。