配置基于 URL 连接的 HTTP 客户端

与AWS SDK for Java 2.x默认版本相比，提供了更轻UrlConnectionHttpClient的 HTTP 客户端。ApacheHttpClientUrlConnectionHttpClient是基于 Java 的URLConnection。

UrlConnectionHttpClient加载速度比基于 Apache 的 HTTP 客户端快，但功能较少。因为它的加载速度更快，所以它是 Java AWS Lambda 函数的好解决方案。

UrlConnectionHttpClient有几个可配置的选项可供您访问。

要了解如何配置基于 Apache 的 HTTP 客户端，请参阅。配置基于 Apache 的 HTTP 客户端

注意

UrlConnectionHttpClient不支持 HTTP 补丁方法。

少数 AWS API 操作需要补丁请求。这些操作名称通常以开头Update*。以下是几个例子。

• AWS Security HubAPI 中的@@ 几个Update*操作以及BatchUpdateFindings操作

• 所有亚马逊 API 网关 API Update*操作

• 亚马逊 WorkDocs API 中的@@ 多项Update*操作

如果你可能使用UrlConnectionHttpClient，请先参考你正在使用的 API 参考。AWS 服务检查您需要的操作是否使用 PATCH 操作。

访问 UrlConnectionHttpClient

要配置和使用UrlConnectionHttpClient，您需要在pom.xml文件中声明对 url-connection-client Maven 工件的依赖关系。

与不同UrlConnectionHttpClient的是ApacheHttpClient，不会自动添加到您的项目中，因此 use 必须对其进行明确声明。

以下pom.xml文件示例显示了使用和配置 HTTP 客户端所需的依赖关系。

<dependencyManagement>
   <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.17.290</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- other dependencies such as s3 or dynamodb -->

<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>url-connection-client</artifactId>
    </dependency>
</dependencies>

配置UrlConnectionHttpClient

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

无论使用哪种方法，您都可以使用 UrlConnectionHttpClient.Builder 为基于 URLConnection 的 HTTP 客户端配置属性。

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

如果您需要配置的实例UrlConnectionHttpClient，我们建议您构建专用实UrlConnectionHttpClient例。你可以使用服务客户端的生成器的httpClientBuilder方法来做到这一点。这样，HTTP 客户端的生命周期由 SDK 管理，这有助于避免在不再需要UrlConnectionHttpClient实例时未关闭实例时可能出现的内存泄漏。

以下示例创建了一个S3Client并将的嵌入式实例配置UrlConnectionHttpClient为maxConnections和connectionTimeout值。HTTP 实例是使用httpClientBuilder方法创建的S3Client.Builder。

以下示例创建了一个S3Client并将的嵌入式实例配置UrlConnectionHttpClient为socketTimeout和proxyConfiguration值。该proxyConfiguration方法采用类型为 Java lambda 的表达式 Consumer<ProxyConfiguration.Builder>。HTTP 实例是使用httpClientBuilder方法创建的S3Client.Builder。

导入

import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import java.net.URI;
import java.time.Duration;

代码

// Singleton: Use the s3Client for all requests.
S3Client s3Client = 
    S3Client.builder()
            .httpClientBuilder(UrlConnectionHttpClient.builder()
                    .socketTimeout(Duration.ofMinutes(5))
                    .proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.mydomain.net:8888"))))
            .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
            .build();

// Perform work with the s3Client.

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

替代方法：共享实UrlConnectionHttpClient例

为了帮助降低应用程序的资源和内存使用率，您可以配置UrlConnectionHttpClient并在多个服务客户端之间共享。HTTP 连接池将被共享，这会降低资源使用量。

注意

共享UrlConnectionHttpClient实例后，您必须在准备好处置时将其关闭。当服务客户端关闭时，SDK 不会关闭实例。

以下示例配置了一个基于 URLConnection 的 HTTP 客户端，该客户端由两个服务客户端使用。配置的UrlConnectionHttpClient实例将传递给服务客户端生成器的httpClient方法。当不再需要服务客户端和 HTTP 客户端时，它们将被明确关闭。HTTP 客户端最后关闭。

导入

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.urlconnection.ProxyConfiguration;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;
import java.time.Duration;

代码

SdkHttpClient urlHttpClient = UrlConnectionHttpClient.create();

// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client = 
    S3Client.builder()
            .httpClient(urlHttpClient)
            .defaultsMode(DefaultsMode.IN_REGION)
            .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
            .build();

DynamoDbClient dynamoDbClient = 
    DynamoDbClient.builder()
                  .httpClient(urlHttpClient)
                  .defaultsMode(DefaultsMode.IN_REGION)
                  .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
                  .build();

// Perform work with the s3Client and dynamoDbClient.

// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
urlHttpClient.close();

URLConnectionHttpClient和ApacheHttpClient一起使用

UrlConnectionHttpClient在应用程序中使用时，必须使用服务客户端生成器的httpClientBuilder方法为每个服务客户端提供一个URLConnectionHttpClientApacheHttpClient实例或一个实例。

如果您的程序使用多个服务客户端，并且以下两个条件都成立，则会出现异常：

• 一个服务客户端配置为使用实UrlConnectionHttpClient例

• 另一个服务客户端使用默认值，ApacheHttpClient但没有明确使用httpClient()或httpClientBuilder()方法构建它

该异常将说明在类路径上找到了多个 HTTP 实现。

以下示例代码片段导致异常。

// The dynamoDbClient uses the UrlConnectionHttpClient
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
        .httpClient(UrlConnectionHttpClient.create())
        .build();

// The s3Client below uses the ApacheHttpClient at runtime, without specifying it.
// An SdkClientException is thrown with the message that multiple HTTP implementations were found on the classpath.
S3Client s3Client = S3Client.create();

// Perform work with the s3Client and dynamoDbClient.

dynamoDbClient.close();
s3Client.close();

通过将显式配置为来S3Client避免异常ApacheHttpClient。

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
        .httpClient(UrlConnectionHttpClient.create())
        .build();

S3Client s3Client = S3Client.builder()
        .httpClient(ApacheHttpClient.create())    // Explicitly build the ApacheHttpClient.
        .build();

// Perform work with the s3Client and dynamoDbClient.

dynamoDbClient.close();
s3Client.close();

注意

要显式创建ApacheHttpClient，必须在 Maven 项目文件中添加对apache-client工件的依赖关系。

代理配置示例

以下代码片段使用了 URL 连接 HTTP 客户端的代理配置生成器。

SdkHttpClient urlHttpClient = UrlConnectionHttpClient.builder()
                .proxyConfiguration(ProxyConfiguration.builder()
                        .endpoint(URI.create("http://example.com:1234"))
                        .username("username")
                        .password("password")
                        .addNonProxyHost("localhost")
                        .addNonProxyHost("host.example.com")
                        .build())
                .build();

代理配置的等效 Java 系统属性显示在以下命令行代码片段中。

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

注意

URL 连接 HTTP 客户端目前不支持 HTTPS 代理系统属性。