配置 AWS 基于 CRT 的 HTTP 客户 - AWS SDK for Java 2.x

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

配置 AWS 基于 CRT 的 HTTP 客户

AWS 基于 CRT 的 HTTP 客户端包括同步客户端AwsCrtHttpClient和异步AwsCrtAsyncHttpClient客户端。 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 客户端是 S 3 AsyncClient 接口的实现,用于与 Amazon S3 服务配合使用。它是基于 Java 的 S3AsyncClient 接口实现的替代方案,具有多种优点。

尽管两个组件都使用AWS 公共运行时中的库,但 AWS 基于 CRT 的 HTTP 客户端不使用 aws-c-s3 库,也不支持 S3 分段上传 API 功能。相比之下, AWS 基于 CRT 的 S3 客户端是专门为支持 S3 分段上传 API 功能而设计的。

访问 AWS 基于 CRT 的 HTTP 客户端

在使用 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>

*将红色显示的版本替换为您要使用的 Java SDK 版本。在 Maven Central 上查找最新消息。

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 上查找最新消息。

2 替换 Uber-Jar 选项将提供的版本。software.amazon.awssdk.crt:aws-crt要确定 AWS CRT 构件版本,请参阅以下步骤

3 将该classifier值替换为适用于您平台的值。有关可用值的列表,请参阅 Java 版 AWS CRT GitHub 页面。

确定 AWS CRT 构件版本的步骤

使用以下步骤来确定与您正在使用的适用于 Java 的 SDK 版本兼容的 AWS CRT 构件版本。

  1. 按照 U ber-jar 选项所示设置您的pom.xml文件。此设置允许您查看默认情况下引入software.amazon.awssdk.crt:aws-crt的 SDK 版本。

  2. 在项目的根目录下(与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
  3. 使用控制台为software.amazon.awssdk.crt:aws-crt构件显示的版本。在这种情况下,请0.31.3添加到您的pom.xml文件中。

使用和配置 AWS 基于 CRT 的 HTTP 客户端

您可以在构建服务客户端的同时配置 AWS 基于 CRT 的 HTTP 客户端,也可以将单个实例配置为在多个服务客户端之间共享。

无论采用哪种方法,您都可以使用生成器来配置 AWS 基于 CRT 的 HTTP 客户端实例的属性

最佳实践:将一个实例专用于一个服务客户端

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

以下示例创建一个 S3 服务客户端,并使用和值配置 AWS 基于 CRT 的 HTTP 客户端connectionTimeoutmaxConcurrency

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();

替代方法:共享 实例

为了帮助降低应用程序的资源和内存使用量,您可以配置 AWS 基于 CRT 的 HTTP 客户端,并在多个服务客户端之间共享该客户端。将共享 HTTP 连接池,从而降低资源使用量。

注意

共享 AWS 基于 CRT 的 HTTP 客户端实例时,您必须在准备好处置时将其关闭。服务客户端关闭后,SDK 不会关闭实例。

以下示例使用connectionTimeoutmaxConcurrency值配置 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 客户端设置为默认客户端

你可以设置你的 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 中央存储库获取最新VERSION值。

注意

如果在一个 pom.xml 文件中声明了多个服务客户端,则所有服务客户端都需要 exclusions XML 元素。

使用 Java 系统属性

要将 AWS 基于 CRT 的 HTTP 客户端用作应用程序的默认 HTTP,可以将 Java 系统属性的software.amazon.awssdk.http.async.service.implsoftware.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 客户端的高级配置

您可以使用 AWS 基于 CRT 的 HTTP 客户端的各种配置设置,包括连接运行状况配置和最大空闲时间。您可以查看适用于 AwsCrtAsyncHttpClient可用配置选项。您可以为 AwsCrtHttpClient 配置相同的选项。

连接运行状况配置

您可以使用 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 支持

AWS 基于 CRT 的 HTTP 客户端尚不支持 HTTP/2 协议,但计划在将来的版本中推出。

同时,如果您使用的是需要 HTTP/2 支持的服务客户端,例如KinesisAsyncClientTranscribeStreamingAsyncClient,请考虑改用。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") .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