HTTP 客户端 - Amazon SDK for Java 2.x
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

HTTP 客户端

您可以使用 Amazon SDK for Java 2.x 更改用于服务客户端的 HTTP 客户端,也可以更改 HTTP 客户端的默认配置。本部分讨论 SDK 的 HTTP 客户端和设置。

SDK for Java 中可用的 HTTP 客户端

同步客户端

SDK for Java 中的同步 HTTP 客户端实现了 SdkHttpClient 接口。同步服务客户端(例如 S3ClientDynamoDbClient)需要使用同步 HTTP 客户端。Amazon SDK for Java 提供三个同步 HTTP 客户端。

ApacheHttpClient(默认)

ApacheHttpClient 是同步服务客户端的默认 HTTP 客户端。有关配置 ApacheHttpClient 的信息,请参阅配置基于 Apache 的 HTTP 客户端

AwsCrtHttpClient

AwsCrtHttpClient 提供高吞吐量和非阻塞 IO。它建立在 Amazon 通用运行时系统(CRT)HTTP 客户端之上。有关配置 AwsCrtHttpClient 并将其用于服务客户端的信息,请参阅配置基于 Amazon CRT 的 HTTP 客户端

UrlConnectionHttpClient

为了最大限度地减少应用程序使用的 jars 和第三方库的数量,您可以使用 UrlConnectionHttpClient。有关配置 UrlConnectionHttpClient 的信息,请参阅配置基于 URLConnection 的 HTTP 客户端

异步客户端

SDK for Java 中的异步 HTTP 客户端实现了 SdkAsyncHttpClient 接口。异步服务客户端(例如 S3AsyncClientDynamoDbAsyncClient)需要使用异步 HTTP 客户端。Amazon SDK for Java 提供了两个异步 HTTP 客户端。

NettyNioAsyncHttpClient(默认)

NettyNioAsyncHttpClient 是异步客户端使用的默认 HTTP 客户端。有关配置 NettyNioAsyncHttpClient 的信息,请参阅配置基于 Netty 的 HTTP 客户端

AwsCrtAsyncHttpClient

AwsCrtAsyncHttpClient 基于 Amazon 通用运行时系统(CRT)HTTP 客户端。有关配置 AwsCrtAsyncHttpClient 的信息,请参阅配置基于 Amazon CRT 的 HTTP 客户端

HTTP 客户端建议

选择 HTTP 客户端实现时,应考虑几个因素。以下信息可帮助您做出决定。

建议流程图

以下流程图提供了一般指导,有助于确定使用哪个 HTTP 客户端。


               HTTP 客户端建议流程图。

HTTP 客户端比较

下表提供了各 HTTP 客户端的详细信息。

HTTP 客户端 同步还是异步 何时使用 限制/缺点
基于 Apache 的 HTTP 客户端

(默认同步 HTTP 客户端)

同步 如果您更需要低延迟而不是高吞吐量,请使用它 与其他 HTTP 客户端相比,启动较慢
基于 URLConnection 的 HTTP 客户端 同步 如果您对限制第三方依赖项有硬性要求,请使用它 不支持某些 API(例如 Amazon API Gateway 的 Update 操作)所要求的 HTTP PATCH 方法
基于 Amazon CRT 的同步 HTTP 客户端1 同步

• 如果您的应用程序在 Amazon Lambda 中运行,请使用它

• 如果您更需要高吞吐量而不是低延迟,请使用它

• 如果您更喜欢同步 SDK 客户端,请使用它

不适用
基于 Netty 的 HTTP 客户端

(默认异步 HTTP 客户端)

异步

• 如果您的应用程序调用需要 HTTP/2 支持的 API,例如 Kinesis API SubscribeToShard,请使用它

与其他 HTTP 客户端相比,启动较慢
基于 Amazon CRT 的异步 HTTP 客户端1 异步

• 如果您的应用程序在 Amazon Lambda 中运行,请使用它

• 如果您更需要高吞吐量而不是低延迟,请使用它

• 如果您更喜欢异步 SDK 客户端,请使用它

• 不支持需要 HTTP/2 支持的服务客户端,例如 KinesisAsynClientTranscribeStreamingAsyncClient

1建议您尽可能使用基于 Amazon CRT 的 HTTP 客户端,因为它具有额外的优点。

智能配置默认值

Amazon SDK for Java 2.x(版本 2.17.102 或更高版本)提供智能配置默认值功能。此功能优化了 HTTP 客户端的两个属性以及不影响 HTTP 客户端的其他属性。

智能配置默认值会根据您提供的默认模式值,为 connectTimeoutInMillistlsNegotiationTimeoutInMillis 属性设置合理的值。您可以根据应用程序的特性选择默认模式值。

有关智能配置默认值以及如何选择最适合应用程序的默认模式值的更多信息,请参阅 Amazon SDKs and Tools Reference Guide

以下是为应用程序设置默认模式的四种方法。

Service client

使用服务客户端生成器直接在服务客户端上配置默认模式。以下示例将 DynamoDbClient 的默认模式设置为 auto

DynamoDbClient ddbClient = DynamoDbClient.builder() .defaultsMode(DefaultsMode.AUTO) .build();
System property

您可以使用 aws.defaultsMode 系统属性来指定默认模式。如果在 Java 中设置系统属性,则需要在初始化任何服务客户端之前设置该属性。

以下示例演示了如何使用在 Java 中设置的系统属性将默认模式设置为 auto

System.setProperty("aws.defaultsMode", "auto");

以下示例演示了如何使用 java 命令的 -D 选项将默认模式设置为 auto

java -Daws.defaultsMode=auto
Environment variable

为环境变量 Amazon_DEFAULTS_MODE 设置一个值以选择应用程序的默认模式。

以下信息显示了使用环境变量将默认模式的值设置为 auto 时,所运行的命令。

操作系统 设置环境变量的命令

Linux、macOS 或 Unix

export Amazon_DEFAULTS_MODE=auto

Windows

set Amazon_DEFAULTS_MODE=auto
Amazon config file

您可以向共享 Amazon config 文件添加 defaults_mode 配置属性,如下例所示。

[default] defaults_mode = auto

如果您使用系统属性、环境变量或 Amazon 配置文件在全局范围内设置了默认模式,则在生成 HTTP 客户端时可以覆盖这些设置。

使用 httpClientBuilder() 方法生成 HTTP 客户端时,设置仅适用于您正在生成的实例。此处显示了此方法一个示例。本示例中基于 Netty 的 HTTP 客户端会覆盖在全局范围内为 connectTimeoutInMillistlsNegotiationTimeoutInMillis 设置的任何默认模式值。

代理支持

您可以使用代码、设置 Java 系统属性或结合使用这两种方法来配置 HTTP 代理。SDK 目前不支持使用环境变量配置代理。

在生成服务客户端时,您可以使用特定于客户端的 ProxyConfiguration 生成器在代码中配置代理。本主题中提及的每个 HTTP 客户端都在其详细介绍部分提供了一个代理配置示例。例如,此处是 Apache HTTP 客户端的示例

HTTP 客户端支持 HTTP 代理的 Java 系统属性
系统属性 描述 HTTP 客户端支持

http.proxyHost

HTTP 代理服务器主机名

全部

http.proxyPort

HTTP 代理服务器端口号

全部

http.proxyUser

HTTP 代理身份验证用户名

全部

http.proxyPassword

HTTP 代理身份验证密码

全部

http.nonProxyHosts

应绕过代理直接访问的主机列表。在使用 HTTPS 时也同样有效

全部

https.proxyHost

HTTPS 代理服务器主机名

Netty、CRT

https.proxyPort

HTTPS 代理服务器端口号

Netty、CRT

https.proxyUser

HTTPS 代理身份验证用户名

Netty、CRT
https.proxyPassword HTTPS 代理身份验证密码 Netty、CRT

表格中所用术语解释:

  • 全部:SDK 提供的所有 HTTP 客户端(UrlConnectionHttpClientApacheHttpClientNettyNioAsyncHttpClientAwsCrtAsyncHttpClient

  • Netty:基于 Netty 的 HTTP 客户端 (NettyNioAsyncHttpClient)

  • CRT:基于 Amazon CRT 的 HTTP 客户端(AwsCrtHttpClientAwsCrtAsyncHttpClient

您可以混合使用 HTTP 客户端配置和系统属性。每个 HTTP 客户端的 ProxyConfiguration 生成器都提供了 useSystemPropertyValues 设置。默认情况下,此设置为 true。当设置为 true 时,SDK 会自动将系统属性值用于未通过 ProxyConfiguration 生成器提供的选项。

以下示例显示了由系统属性和代码提供的配置。

// Command line with the proxy password set as a system property. $ java -Dhttp.proxyPassword=password -cp ... App // Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will supplement // the proxy configuration in code with the 'http.proxyPassword' value from the system property. SdkHttpClient apacheHttpClient = ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://localhost:1234")) .username("username") .build()) .build(); // Use the apache HTTP client with proxy configuration. DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(apacheHttpClient) .build();
注意

您可以使用以下系统属性,而不是像前面的代码片段所示的那样在代码中设置 endpoint 属性。

-Dhttp.proxyHost=localhost -Dhttp.proxyPort=1234