AWS CRT基于配置的HTTP客户端 - AWS SDK for Java 2.x
访问 AWS CRT基于的HTTP客户端使用和配置 AWS CRT基于HTTP客户端的客户端将 AWS CRT基于HTTP客户端的客户端设置为默认客户端高级配置HTTP/2 支持代理配置示例

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

AWS CRT基于配置的HTTP客户端

AWS CRT基于的HTTP客户端包括同步AwsCrtHttpClient和异步客户端AwsCrtAsyncHttpClient。 AWS CRT基于HTTP客户端的客户可为客户提供以下HTTP好处：

  • 更快的SDK启动时间

  • 更小的内存占用空间

  • 缩短了延迟时间

  • 连接运行状况管理

  • DNS负载平衡

AWS CRT中基于的组件 SDK

本主题中描述 AWS CRT的基于HTTP客户端和 AWS CRT基于 S3 的客户端是中的不同组件SDK。

AWS CRT基于同步和异步的HTTP客户端是实现SDKHTTP客户端接口，用于一般HTTP通信。它们是中其他同步或异步HTTP客户端的替代方案SDK，还有其他好处。

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 显示了使用物料清单 (BOM) 机制声明的 AWS CRT基于的HTTP客户端。

<project>
   <properties>
     <aws.sdk.version>2.27.21</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 存储库以获取最新版本。

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

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

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

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

如果您需要配置 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;

代码

// 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不会关闭实例。

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

您可以设置您的 Maven 构建文件，让SDK使用 AWS CRT基于HTTP客户端的客户端作为服务HTTP客户端的默认客户端。

为此，您可以向每个服务客户端工件添加一个具有默认HTTP客户端依赖关系的exclusions元素。

在以下pom.xml示例中，SDK使用 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文件中声明了多个服务客户端，则所有服务客户端都需要该exclusionsXML元素。

使用 Java 系统属性

要将 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基于poml.xml文件的HTTP客户端的使用时，你需要在文件中添加对aws-crt-client工件的依赖关系。

AWS CRT基于HTTP客户端的高级配置

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

连接运行状况配置

您可以使用客户端生成器上的connectionHealthConfiguration方法为 AWS CRT基于HTTP客户端的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 协议，但计划在 future 版本中推出。

同时，如果您使用的是需要 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")
        .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