本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 中設定 HTTP 用戶端 AWS SDK for Java 2.x
您可以變更 HTTP 用戶端以用於您的服務用戶端，以及使用 變更 HTTP 用戶端的預設組態 AWS SDK for Java 2.x。本節討論 開發套件的 HTTP 用戶端和設定。
## 適用於 Java 的 開發套件中可用的 HTTP 用戶端
### 同步用戶端
適用於 Java 的 SDK 中的同步 HTTP 用戶端實作 [SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html) 介面。同步服務用戶端，例如 `S3Client`或 `DynamoDbClient`，需要使用同步 HTTP 用戶端。 適用於 Java 的 AWS SDK 提供三個同步 HTTP 用戶端。
**ApacheHttpClient （預設）**
[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) 是同步服務用戶端的預設 HTTP 用戶端。如需設定 的資訊`ApacheHttpClient`，請參閱 [設定 Apache 型 HTTP 用戶端](http-configuration-apache.md)。
**AwsCrtHttpClient**
[AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) 提供高輸送量和非封鎖 IO。它建置在 AWS 通用執行期 (CRT) Http 用戶端上。如需設定 `AwsCrtHttpClient`並搭配 服務用戶端使用的資訊，請參閱 [設定 AWS CRT 型 HTTP 用戶端](http-configuration-crt.md)。
**UrlConnectionHttpClient**
若要將您應用程式使用的 jar 和第三方程式庫數量降至最低，您可以使用 [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)。如需設定 的資訊`UrlConnectionHttpClient`，請參閱 [設定 URLConnection 型 HTTP 用戶端](http-configuration-url.md)。
**Apache5HttpClient**
[Apache5HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) 是`ApacheHttpClient`建置在 *Apache 5.x HttpClient 上的更新版本。5.x 版*是 Apache 主動維護的版本，透過提供現代 Java 生態系統相容性`ApacheHttpClient`，包括 Java 21 的虛擬執行緒支援，以及透過 SLF4J 增強的記錄靈活性，來改善先前使用的版本。 `Apache5HttpClient`將在未來版本的適用於 Java 2.x 的 AWS SDK 中取代`ApacheHttpClient`為預設同步用戶端。它具有相同的 API 和功能，使其成為插入式取代的理想選擇。如需設定 的資訊`Apache5HttpClient`，請參閱 [設定 Apache 5.x 型 HTTP 用戶端](http-configuration-apache5.md)。
### 非同步用戶端
適用於 Java 的 SDK 中的非同步 HTTP 用戶端實作 [SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html) 介面。非同步服務用戶端，例如 `S3AsyncClient`或 `DynamoDbAsyncClient`，需要使用非同步 HTTP 用戶端。 適用於 Java 的 AWS SDK 提供兩個非同步 HTTP 用戶端。
**NettyNioAsyncHttpClient （預設）**
[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) 是非同步用戶端使用的預設 HTTP 用戶端。如需設定 的資訊`NettyNioAsyncHttpClient`，請參閱 [設定 Netty 型 HTTP 用戶端](http-configuration-netty.md)。
**AwsCrtAsyncHttpClient**
[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) 是以 AWS 通用執行期 (CRT) HTTP 用戶端為基礎。如需設定 的資訊`AwsCrtAsyncHttpClient`，請參閱 [設定 AWS CRT 型 HTTP 用戶端](http-configuration-crt.md)。
## HTTP 用戶端建議
當您選擇 HTTP 用戶端實作時，有幾個因素發揮作用。使用下列資訊來協助您做出決定。
### 建議流程圖
下列流程圖提供一般指引，協助您判斷要使用的 HTTP 用戶端。
![\[HTTP 用戶端建議的流程圖。\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/images/JavaDevGuide-HTTPflowchart-DI.png)
### HTTP 用戶端比較
下表提供每個 HTTP 用戶端的詳細資訊。
| HTTP 用戶端 | 同步或非同步 | 使用情況 | 限制/回撥 |
| --- | --- | --- | --- |
| Apache 型 HTTP 用戶端 *（預設同步 HTTP 用戶端）* | Sync | 如果您偏好低延遲而非高輸送量，請使用它 | 與其他 HTTP 用戶端相比，啟動時間較慢 |
| URLConnection 型 HTTP 用戶端 | Sync | 如果您有限制第三方相依性的硬性需求，請使用它 | 不支援 HTTP PATCH 方法，某些 APIS 需要此方法，例如 Amazon APIGateway Update 操作 |
| AWS CRT 型同步 HTTP 用戶端1 | Sync | • 如果您的應用程式在 中執行，請使用它 AWS Lambda • 如果您偏好高輸送量而非低延遲，請使用它 • 如果您偏好同步 SDK 用戶端，請使用它 | 不支援下列 Java 系統屬性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/http-configuration.html) |
| Netty 型 HTTP 用戶端 *（預設非同步 HTTP 用戶端）* | 非同步 | • 如果您的應用程式叫用需要 HTTP/2 支援的 APIs，例如 Kinesis API [SubscribeToShard](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_SubscribeToShard.html)，請使用它 | 與其他 HTTP 用戶端相比，啟動時間較慢 |
| AWS 以 CRT 為基礎的非同步 HTTP 用戶端1 | 非同步 | • 如果您的應用程式在 中執行，請使用它 AWS Lambda• 如果您偏好高輸送量而非低延遲，請使用它• 如果您偏好非同步 SDK 用戶端，請使用它 | • 不支援需要 HTTP/2 支援的服務用戶端，例如 `KinesisAsynClient`和 `TranscribeStreamingAsyncClient` 不支援下列 Java 系統屬性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/http-configuration.html) |
1由於其新增優點，我們建議您盡可能使用 AWS CRT 型 HTTP 用戶端。
## 智慧組態預設值
AWS SDK for Java 2.x (2.17.102 版或更新版本） 提供智慧型組態預設功能。此功能可最佳化兩個 HTTP 用戶端屬性，以及其他不會影響 HTTP 用戶端的屬性。
智慧組態預設值會根據您提供的預設值模式值，設定 `connectTimeoutInMillis`和 `tlsNegotiationTimeoutInMillis` 屬性的合理值。您可以根據應用程式的特性選擇預設模式值。
如需智慧組態預設值以及如何選擇最適合您應用程式的預設模式值的詳細資訊，請參閱 [AWS SDKs和工具參考指南](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html)。
以下是為您的應用程式設定預設模式的四種方法。
------
#### [ Service client ]
使用服務用戶端建置器直接在服務用戶端上設定預設模式。下列範例會將 的預設模式設定為 `auto` `DynamoDbClient`。
```
DynamoDbClient ddbClient = DynamoDbClient.builder()
.defaultsMode(DefaultsMode.AUTO)
.build();
```
------
#### [ System property ]
您可以使用`aws.defaultsMode`系統屬性來指定預設模式。如果您在 Java 中設定系統屬性，則需要在初始化任何服務用戶端之前設定 屬性。
下列範例說明如何`auto`使用 Java 中的系統屬性集，將預設模式設定為 。
```
System.setProperty("aws.defaultsMode", "auto");
```
下列範例示範如何使用 `java`命令`auto``-D`的選項，將預設模式設定為 。
```
java -Daws.defaultsMode=auto
```
------
#### [ Environment variable ]
設定環境變數的值`AWS_DEFAULTS_MODE`，為您的應用程式選取預設模式。
下列資訊顯示執行 命令，以`auto`使用 環境變數將預設模式的值設定為 。
| 作業系統 | 用於設定環境變數的命令 |
| --- | --- |
| Linux、macOS 或 Unix | export AWS\$1DEFAULTS\$1MODE=auto |
| Windows | set AWS\$1DEFAULTS\$1MODE=auto |
------
#### [ AWS config file ]
您可以將`defaults_mode`組態屬性新增至共用 AWS `config`檔案，如下列範例所示。
```
[default]
defaults_mode = auto
```
------
如果您使用系統屬性、環境變數或 AWS 組態檔案全域設定預設模式，您可以在建置 HTTP 用戶端時覆寫設定。
當您使用 `httpClientBuilder()`方法建置 HTTP 用戶端時，設定僅適用於您正在建置的執行個體。[此處](http-configuration-netty.md#http-config-netty-one-client)顯示範例。此範例中的 Netty 型 HTTP 用戶端會覆寫 `connectTimeoutInMillis`和 全域設定的任何預設模式值`tlsNegotiationTimeoutInMillis`。
# 設定 Apache 型 HTTP 用戶端
中的同步服務用戶端預設 AWS SDK for Java 2.x 使用 Apache 型 HTTP 用戶端 [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)。開發套件的 `ApacheHttpClient` 是以 Apache [HttpClient](https://hc.apache.org/httpcomponents-client-4.5.x/index.html) 為基礎。
軟體開發套件也提供 [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)，可更快速載入，但功能較少。如需設定 的資訊`UrlConnectionHttpClient`，請參閱 [設定 URLConnection 型 HTTP 用戶端](http-configuration-url.md)。
若要查看您可用於 的完整組態選項集`ApacheHttpClient`，請參閱 [ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html) 和 [ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html)。
## 存取 `ApacheHttpClient`
在大多數情況下，您會在沒有任何明確組態`ApacheHttpClient`的情況下使用 。您宣告您的服務用戶端，開發套件將使用`ApacheHttpClient`標準值為您設定 。
如果您想要明確設定 `ApacheHttpClient` 或將其與多個服務用戶端搭配使用，則需要將其用於組態。
### 不需要組態
當您在 Maven 中宣告對服務用戶端的相依性時，軟體開發套件會新增對`apache-client`成品的*執行時間*相依性。這可讓 `ApacheHttpClient`類別在執行時間可供您的程式碼使用，但無法在編譯時間使用。如果您未設定 Apache 型 HTTP 用戶端，則不需要為其指定相依性。
在 Maven `pom.xml` 檔案的下列 XML 程式碼片段中，向 宣告的相依性`s3`會自動帶入以 Apache 為基礎的 HTTP 用戶端。您不需要特別為其宣告相依性。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
s3
```
使用這些相依性時，您無法進行任何明確的 HTTP 組態變更，因為程式`ApacheHttpClient`庫僅位於執行時間 classpath 上。
### 需要的配置
若要設定 `ApacheHttpClient`，您需要在*編譯*時在程式`apache-client`庫上新增相依性。
請參閱下列 Maven `pom.xml` 檔案的範例來設定 `ApacheHttpClient`。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
s3
software.amazon.awssdk
apache-client
```
## 使用和設定 `ApacheHttpClient`
您可以設定 執行個體`ApacheHttpClient`以及建置服務用戶端，也可以設定單一執行個體以在多個服務用戶端之間共用。
使用任一方法，您可以使用 `[ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html)`來設定 Apache 型 HTTP 用戶端的屬性。
### 最佳實務：將`ApacheHttpClient`執行個體專用於服務用戶端
如果您需要設定 的執行個體`ApacheHttpClient`，我們建議您建置專用`ApacheHttpClient`執行個體。您可以使用服務用戶端建置器的 `httpClientBuilder`方法來執行此操作。如此一來，HTTP 用戶端的生命週期由 SDK 管理，這有助於避免在`ApacheHttpClient`執行個體不再需要時關閉時造成潛在的記憶體流失。
下列範例會建立 ，`S3Client`並使用 `ApacheHttpClient``maxConnections`和 `connectionTimeout`值設定 的內嵌執行個體。HTTP 執行個體是使用 的 `httpClientBuilder`方法建立。 `S3Client.Builder`
**匯入**
```
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(ApacheHttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
).build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
### 替代方法：共用`ApacheHttpClient`執行個體
為了協助降低應用程式的資源和記憶體用量，您可以設定 ，`ApacheHttpClient`並在多個服務用戶端之間共用。HTTP 連線集區將共用，這會降低資源用量。
**注意**
共用`ApacheHttpClient`執行個體時，您必須在準備好進行處置時將其關閉。當服務用戶端關閉時，軟體開發套件不會關閉執行個體。
下列範例會設定兩個服務用戶端所使用的 Apache 型 HTTP 用戶端。設定的`ApacheHttpClient`執行個體會傳遞至每個建置器的 `httpClient`方法。當不再需要服務用戶端和 HTTP 用戶端時，程式碼會明確關閉它們。程式碼最後會關閉 HTTP 用戶端。
**匯入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apacheHttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apacheHttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apacheHttpClient.close(); // Explicitly close apacheHttpClient.
```
## Proxy 組態範例
下列程式碼片段使用 [Apache HTTP 用戶端的代理組態建置器](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html)。
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.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=localhost|host.example.com -cp ... App
```
使用環境變數的同等設定為：
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**注意**
Apache HTTP 用戶端目前不支援 HTTPS 代理系統屬性或 HTTPS\$1PROXY 環境變數。
# 設定 URLConnection 型 HTTP 用戶端
相較於預設 ， AWS SDK for Java 2.x 提供更輕量的 `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)` HTTP 用戶端`ApacheHttpClient`。`UrlConnectionHttpClient` 是以 Java 的 為基礎`[URLConnection](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/URLConnection.html)`。
`UrlConnectionHttpClient` 載入速度比 Apache 型 HTTP 用戶端更快，但功能較少。因為它的載入速度更快，因此是 Java AWS Lambda 函數的理想[解決方案](lambda-optimize-starttime.md)。
`UrlConnectionHttpClient` 有數個[可設定的選項](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html)可供您存取。
**注意**
`UrlConnectionHttpClient` 不支援 HTTP PATCH 方法。
少數 AWS API 操作需要 PATCH 請求。這些操作名稱通常以 開頭`Update*`。以下是幾個範例。
AWS Security Hub CSPM API 和 [BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html) [`Update*`操作中的數個](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Operations.html)操作
所有 Amazon API Gateway API [`Update*`操作](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html)
如果您可以使用 `UrlConnectionHttpClient`，請先參閱您正在使用的 AWS 服務 的 API 參考。檢查您所需的操作是否使用 PATCH 操作。
## 存取 `UrlConnectionHttpClient`
若要設定和使用 `UrlConnectionHttpClient`，您可以宣告對 `pom.xml` 檔案中 `url-connection-client` Maven 成品的相依性。
與 不同`ApacheHttpClient`， `UrlConnectionHttpClient` 不會自動新增至您的專案，因此使用 必須特別宣告。
下列`pom.xml`檔案範例顯示使用和設定 HTTP 用戶端所需的相依性。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
url-connection-client
```
## 使用和設定 `UrlConnectionHttpClient`
您可以設定 執行個體`UrlConnectionHttpClient`以及建置服務用戶端，也可以設定單一執行個體以在多個服務用戶端之間共用。
透過任一方法，您可以使用 [UrlConnectionHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html) 來設定 URLConnection 型 HTTP 用戶端的屬性。
### 最佳實務：將`UrlConnectionHttpClient`執行個體專用於服務用戶端
如果您需要設定 的執行個體`UrlConnectionHttpClient`，我們建議您建置專用`UrlConnectionHttpClient`執行個體。您可以使用服務用戶端建置器的 `httpClientBuilder`方法來執行此操作。如此一來，HTTP 用戶端的生命週期由 SDK 管理，這有助於避免在`UrlConnectionHttpClient`執行個體不再需要時關閉時造成潛在的記憶體流失。
下列範例會建立 ，`S3Client`並使用 `UrlConnectionHttpClient``socketTimeout`和 `proxyConfiguration`值設定 的內嵌執行個體。`proxyConfiguration` 方法採用類型 的 Java lambda 表達式` Consumer<[ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)>`。
**匯入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import java.net.URI;
import java.time.Duration;
```
**Code**
```
// 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`執行個體時，您必須在準備好進行處置時將其關閉。當服務用戶端關閉時，軟體開發套件不會關閉執行個體。
下列範例會設定兩個服務用戶端所使用的 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;
```
**Code**
```
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`方法，為每個服務用戶端提供`URLConnectionHttpClient`執行個體或`ApacheHttpClient`執行個體。
如果您的程式使用多個服務用戶端，且符合下列兩項，則會發生例外狀況：
+ 一個服務用戶端設定為使用`UrlConnectionHttpClient`執行個體
+ 另一個服務用戶端使用預設值，`ApacheHttpClient`而不使用 `httpClient()`或 `httpClientBuilder()`方法明確建置預設值
例外狀況將指出在 classpath 上找到多個 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`成品[新增相依性](http-configuration-apache.md#http-apache-dependency)。
## Proxy 組態範例
下列程式碼片段使用適用於 [URL 連線 HTTP 用戶端的代理組態建置器](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)。
```
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=localhost|host.example.com -cp ... App
```
使用環境變數的同等設定為：
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**注意**
URLConnection 型 HTTP 用戶端目前不支援 HTTPS 代理系統屬性或 HTTPS\$1PROXY 環境變數。
# 設定 Netty 型 HTTP 用戶端
中非同步操作的預設 HTTP 用戶端 AWS SDK for Java 2.x 是 Netty 型 [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)。Netty 型用戶端是以 [Netty 專案](https://netty.io/)的非同步事件驅動型網路架構為基礎。
做為替代 HTTP 用戶端，您可以使用新的 [AWS CRT 型 HTTP 用戶端](http-configuration-crt.md)。本主題說明如何設定 `NettyNioAsyncHttpClient`。
## 存取 `NettyNioAsyncHttpClient`
在大多數情況下，您會在非同步程式中使用 ，`NettyNioAsyncHttpClient`而不需要任何明確的組態。您宣告非同步服務用戶端，開發套件會為您設定`NettyNioAsyncHttpClient`標準值的 。
如果您想要明確設定 `NettyNioAsyncHttpClient` 或將其與多個服務用戶端搭配使用，則需要將其用於組態。
### 不需要組態
當您在 Maven 中宣告對服務用戶端的相依性時，軟體開發套件會新增對`netty-nio-client`成品的*執行時間*相依性。這可讓 `NettyNioAsyncHttpClient`類別在執行時間可供您的程式碼使用，但無法在編譯時間使用。如果您未設定 Netty 型 HTTP 用戶端，則不需要為其指定相依性。
在 Maven `pom.xml` 檔案的下列 XML 程式碼片段中，宣告為 的相依性`dynamodb-enhanced`會暫時帶入 Netty 型 HTTP 用戶端。您不需要特別為其宣告相依性。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
dynamodb-enhanced
```
使用這些相依性時，您無法進行任何 HTTP 組態變更，因為程式`NettyNioAsyncHttpClient`庫僅位於執行時間 classpath 上。
### 需要的配置
若要設定 `NettyNioAsyncHttpClient`，您需要在*編譯*時對`netty-nio-client`成品新增相依性。
請參閱下列 Maven `pom.xml` 檔案的範例來設定 `NettyNioAsyncHttpClient`。
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
dynamodb-enhanced
software.amazon.awssdk
netty-nio-client
```
## 使用和設定 `NettyNioAsyncHttpClient`
您可以設定 執行個體`NettyNioAsyncHttpClient`以及建置服務用戶端，也可以設定單一執行個體以在多個服務用戶端之間共用。
透過任一方法，您可以使用 [NettyNioAsyncHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html) 來設定 Netty 型 HTTP 用戶端執行個體的屬性。
### 最佳實務：將`NettyNioAsyncHttpClient`執行個體專用於服務用戶端
如果您需要設定 的執行個體`NettyNioAsyncHttpClient`，我們建議您建置專用`NettyNioAsyncHttpClient`執行個體。您可以使用服務用戶端建置器的 `httpClientBuilder`方法來執行此操作。如此一來，HTTP 用戶端的生命週期由 SDK 管理，這有助於避免在`NettyNioAsyncHttpClient`執行個體不再需要時關閉時造成潛在的記憶體流失。
下列範例會建立`DynamoDbAsyncClient`執行個體所使用的`DynamoDbEnhancedAsyncClient`執行個體。`DynamoDbAsyncClient` 執行個體包含具有 `connectionTimeout`和 `maxConcurrency`值的`NettyNioAsyncHttpClient`執行個體。HTTP 執行個體是使用 的 `httpClientBuilder`方法建立。 `DynamoDbAsyncClient.Builder`
**匯入**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
import software.amazon.awssdk.enhanced.dynamodb.extensions.AutoGeneratedTimestampRecordExtension;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import java.time.Duration;
```
**Code**
```
// DynamoDbAsyncClient is the lower-level client used by the enhanced client.
DynamoDbAsyncClient dynamoDbAsyncClient =
DynamoDbAsyncClient
.builder()
.httpClientBuilder(NettyNioAsyncHttpClient.builder()
.connectionTimeout(Duration.ofMillis(5_000))
.maxConcurrency(100)
.tlsNegotiationTimeout(Duration.ofMillis(3_500)))
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Singleton: Use dynamoDbAsyncClient and enhancedClient for all requests.
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient
.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with the dynamoDbAsyncClient and enhancedClient.
// Requests completed: Close dynamoDbAsyncClient.
dynamoDbAsyncClient.close();
```
### 替代方法：共用`NettyNioAsyncHttpClient`執行個體
為了協助降低應用程式的資源和記憶體用量，您可以設定 ，`NettyNioAsyncHttpClient`並在多個服務用戶端之間共用。HTTP 連線集區將共用，這會降低資源用量。
**注意**
共用`NettyNioAsyncHttpClient`執行個體時，您必須在準備好進行處置時將其關閉。當服務用戶端關閉時，軟體開發套件不會關閉執行個體。
下列範例會設定兩個服務用戶端所使用的 Netty 型 HTTP 用戶端。設定的`NettyNioAsyncHttpClient`執行個體會傳遞至每個建置器的 `httpClient`方法。當不再需要服務用戶端和 HTTP 用戶端時，程式碼會明確關閉它們。程式碼最後會關閉 HTTP 用戶端。
**匯入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
// Create a NettyNioAsyncHttpClient shared instance.
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder().maxConcurrency(100).build();
// Singletons: Use the s3AsyncClient, dbAsyncClient, and enhancedAsyncClient for all requests.
S3AsyncClient s3AsyncClient =
S3AsyncClient.builder()
.httpClient(nettyHttpClient)
.build();
DynamoDbAsyncClient dbAsyncClient =
DynamoDbAsyncClient.builder()
.httpClient(nettyHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbEnhancedAsyncClient enhancedAsyncClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with s3AsyncClient, dbAsyncClient, and enhancedAsyncClient.
// Requests completed: Close all service clients.
s3AsyncClient.close();
dbAsyncClient.close()
nettyHttpClient.close(); // Explicitly close nettyHttpClient.
```
## 設定 ALPN 通訊協定交涉
ALPN (Application-Layer Protocol Negotiation) 是一種 TLS 延伸模組，可讓應用程式層交涉應透過安全連線執行的通訊協定，以避免額外的往返並提供更好的效能。
若要讓 Netty 型 HTTP 用戶端使用 ALPN，請呼叫建置器方法，如下列程式碼片段所示：
```
import software.amazon.awssdk.http.Protocol;
import software.amazon.awssdk.http.ProtocolNegotiation;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient;
// Configure the Netty-based HTTP client to use the ALPN protocol.
SdkAsyncHttpClient nettyClient = NettyNioAsyncHttpClient.builder()
.protocol(Protocol.HTTP2)
.protocolNegotiation(ProtocolNegotiation.ALPN)
.build();
// Use the Netty-based HTTP client with a service client.
TranscribeStreamingAsyncClient transcribeClient = TranscribeStreamingAsyncClient.builder()
.httpClient(nettyClient)
.build();
```
ALPN 通訊協定交涉目前僅適用於 HTTP/2 通訊協定，如上一個程式碼片段所示。
## Proxy 組態範例
下列程式碼片段使用 [Netty HTTP 用戶端的代理組態建置器](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/ProxyConfiguration.Builder.html)。
```
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.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`。如果未在程式碼中設定結構描述屬性，則結構描述預設為 HTTP，開發套件只會尋找`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 nettyHttpClient = NettyNioAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
# 設定 AWS CRT 型 HTTP 用戶端
AWS CRT 型 HTTP 用戶端包含同步 [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) 和非同步 [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)。 AWS CRT 型 HTTP 用戶端提供下列 HTTP 用戶端優點：
+ 更快速的 SDK 啟動時間
+ 記憶體佔用空間較小
+ 延遲時間縮短
+ 連線運作狀態管理
+ DNS 負載平衡
**AWS 開發套件中的 CRT 型元件**
本主題中所述的 AWS CRT 型* HTTP* 用戶端和 AWS CRT 型 *S3* 用戶端是 SDK 中的不同元件。
同步和非同步 **AWS CRT 型 HTTP 用戶端**是 SDK HTTP 用戶端介面的實作，用於一般 HTTP 通訊。它們是 SDK 中其他同步或非同步 HTTP 用戶端的替代方案，具有其他優點。
**[AWS CRT 型 S3 用戶端](crt-based-s3-client.md)**是 [S3AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) 界面的實作，用於使用 Amazon S3 服務。這是以 Java 為基礎的`S3AsyncClient`介面實作的替代方案，並提供多種優點。
雖然這兩個元件都使用[AWS 通用執行期](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)的程式庫，但以 AWS CRT 為基礎的 HTTP 用戶端不會使用 [aws-c-s3 程式庫](https://github.com/awslabs/aws-c-s3)，也不支援 [S3 分段上傳 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 功能。相較之下， AWS CRT 型 S3 用戶端是專為支援 S3 分段上傳 API 功能而打造。
## 存取 AWS CRT 型 HTTP 用戶端
在使用 AWS CRT 型 HTTP 用戶端之前，請先將最低版本為 2.22.0 的`aws-crt-client`成品新增至專案的相依性。
使用下列其中一個選項來設定 Maven `pom.xml` 檔案。
**注意**
如果您需要將執行時間相依性的大小縮小，例如，如果您的應用程式在 AWS Lambda 函數中執行，您可以選擇使用*平台特定的 jar 選項*。
------
#### [ Uber-jar option ]
根據預設， `aws-crt-client`會使用 uber-jar 的 AWS CRT 成品，其中包含多個平台的二進位檔，包括 Linux、Windows 和 macOS。
```
2.29.10*
software.amazon.awssdk
bom
${aws.sdk.version}
pom
import
software.amazon.awssdk
aws-crt-client
```
\$1將紅色顯示的版本取代為您要使用的 Java 開發套件版本。尋找 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 的最新資訊。
------
#### [ Platform-specific jar option ]
若要將 Java 執行時間限制為 AWS CRT 程式庫的平台特定版本，請對 *Uber-jar 選項*進行下列變更。
+ 將 `exclusions`元素新增至 SDK 的`aws-crt-client`成品。此排除可防止 SDK 暫時使用 AWS CRT uber-jar。
+ 為您需要的特定 AWS CRT 平台版本新增相依性元素。請參閱以下步驟**以判斷 AWS CRT 成品版本**，了解如何判斷正確的版本。
```
2.29.101
software.amazon.awssdk
bom
${aws.sdk.java.version}
pom
import
software.amazon.awssdk
aws-crt-client
software.amazon.awssdk.crt
aws-crt
software.amazon.awssdk.crt
aws-crt
0.31.32
linux-x86_643
```
1將紅色顯示的版本取代為您要使用的 Java 開發套件版本。尋找 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 的最新資訊。
2取代由 *Uber-jar 選項*`software.amazon.awssdk.crt:aws-crt`提供的 版本。請參閱**下列步驟以判斷 AWS CRT 成品版本**。
3將 `classifier`值取代為您的平台。如需[可用值的清單](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars)，請參閱適用於 Java 的 AWS CRT GitHub 頁面。
**判斷 AWS CRT 成品版本的步驟**
使用下列步驟來判斷與您所使用的適用於 Java 的 開發套件版本相容的 AWS CRT 成品版本。
1. 如 *Uber-jar 選項*所示設定您的`pom.xml`檔案。此設定可讓您查看軟體`software.amazon.awssdk.crt:aws-crt`開發套件預設導入的版本。
1. 在專案的根目錄 （與 `pom.xml` 檔案位於相同的目錄中），執行下列 Maven 命令：
```
mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt
```
Maven 可能會執行其他動作，但最終您應該會看到 SDK 暫時使用的`software.amazon.awssdk.crt:aws-crt`相依性的主控台輸出。下列程式碼片段顯示以 開發套件版本為基礎的範例輸出`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
```
1. 使用主控台為`software.amazon.awssdk.crt:aws-crt`成品顯示的版本。在此情況下，請將 `0.31.3`新增至您的 `pom.xml` 檔案。
------
## 使用和設定 AWS CRT 型 HTTP 用戶端
您可以設定以 AWS CRT 為基礎的 HTTP 用戶端，以及建置服務用戶端，也可以設定單一執行個體在多個服務用戶端之間共用。
使用任一種方法，您可以使用建置器來[設定 CRT 型 HTTP 用戶端執行個體的屬性](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html)。 AWS
### 最佳實務：將執行個體專用於服務用戶端
如果您需要設定 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;
```
**Code**
```
// 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;
```
**Code**
```
// 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 用戶端執行個體時，您必須在準備好進行處置時將其關閉。當服務用戶端關閉時，軟體開發套件不會關閉執行個體。
下列範例會使用 `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;
```
**Code**
```
// 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;
```
**Code**
```
// 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`範例中，軟體開發套件使用適用於 S3 服務的 AWS CRT 型 HTTP 用戶端。如果程式碼中的服務用戶端是 `S3AsyncClient`，則 SDK 會使用 `AwsCrtAsyncHttpClient`。如果服務用戶端是 S3Client，則 SDK 會使用 `AwsCrtHttpClient`。透過此設定，預設 Netty 型非同步 HTTP 用戶端和預設 Apache 型同步 HTTP 無法使用。
```
VERSION
software.amazon.awssdk
s3
${aws.sdk.version}
software.amazon.awssdk
netty-nio-client
software.amazon.awssdk
apache-client
software.amazon.awssdk
aws-crt-client
```
請造訪 Maven 中央儲存庫以取得最新的 [https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 值。
**注意**
如果在`pom.xml`檔案中宣告多個服務用戶端，則所有 都需要 `exclusions` XML 元素。
### 使用 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 型 HTTP 用戶端的使用時，您需要在`poml.xml`檔案中的`aws-crt-client`成品上新增相依性。
## AWS CRT 型 HTTP 用戶端的進階組態
您可以使用 AWS CRT 型 HTTP 用戶端的各種組態設定，包括連線運作狀態組態和閒置時間上限。您可以檢閱 [可用的組態選項](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html)`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;
```
**Code**
```
// 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;
```
**Code**
```
// 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 支援的服務用戶端，例如 [KinesisAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html) 或 [TranscribeStreamingAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/transcribestreaming/TranscribeStreamingAsyncClient.html)，請考慮改用 [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)。
## Proxy 組態範例
下列程式碼片段顯示[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html)您使用 來設定程式碼中的代理設定。
------
#### [ Synchronous client ]
**匯入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**Code**
```
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;
```
**Code**
```
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`。如果未在程式碼中設定結構描述屬性，則結構描述預設為 HTTP，開發套件只會尋找`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
```
# 設定 HTTP 代理
您可以使用程式碼、設定 Java 系統屬性或設定環境變數來設定 HTTP 代理。
## 在程式碼中設定
您可以在建置服務用戶端時，使用用戶端特定的`ProxyConfiguration`建置器在程式碼中設定代理。下列程式碼顯示 Amazon S3 服務用戶端所使用的 Apache 型 HTTP 用戶端代理組態範例。
```
SdkHttpClient httpClient1 = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://proxy.example.com"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.build())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(httpClient)
.build();
```
本主題中每個 HTTP 用戶端的 區段會顯示代理組態範例。
+ [Apache HTTP 用戶端](http-configuration-apache.md#http-configuration-apache-proxy-conf-ex)
+ [URLConnection 型 HTTP 用戶端](http-configuration-url.md#http-configuration-url-proxy-conf-ex)
+ [Netty 型 HTTP 用戶端](http-configuration-netty.md#http-config-netty-proxy-ex)
+ [AWS CRT 型 HTTP 用戶端](http-configuration-crt.md#http-config-crt-proxy-ex)
## 使用外部設定設定 HTTP 代理
即使您未在程式碼中明確使用`ProxyConfiguration`建置器，軟體開發套件仍會尋找外部設定來設定預設代理組態。
根據預設，軟體開發套件會先搜尋 JVM 系統屬性。如果找到一個屬性，開發套件會使用 值和任何其他系統屬性值。如果沒有可用的系統屬性，軟體開發套件會尋找代理環境變數。
SDK 可以使用下列 Java 系統屬性和環境變數。
**Java 系統屬性**
| 系統屬性 | Description | HTTP 用戶端支援 |
| --- | --- | --- |
| http.proxyHost | HTTP 代理伺服器的主機名稱 | 全部 |
| http.proxyPort | HTTP 代理伺服器的連接埠號碼 | 全部 |
| http.proxyUser | HTTP 代理身分驗證的使用者名稱 | 全部 |
| http.proxyPassword | HTTP 代理身分驗證的密碼 | 全部 |
| http.nonProxyHosts | 應直接到達的主機清單，略過代理。[使用 HTTPS 時，此清單也有效](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html)。 | 全部 |
| https.proxyHost | HTTPS 代理伺服器的主機名稱 | Netty、CRT |
| https.proxyPort | HTTPS 代理伺服器的連接埠號碼 | Netty、CRT |
| https.proxyUser | HTTPS 代理身分驗證的使用者名稱 | Netty、CRT |
| https.proxyPassword | HTTPS 代理身分驗證的密碼 | Netty、CRT |
**環境變數**
| 環境變數 | Description | HTTP 用戶端支援 |
| --- | --- | --- |
| HTTP\$1PROXY1 | 具有 HTTP 結構描述的有效 URL | 全部 |
| HTTPS\$1PROXY1 | 具有 HTTPS 方案的有效 URL | Netty、CRT |
| NO\$1PROXY2 | 應直接到達的主機清單，略過代理。此清單對 HTTP 和 HTTPS 都有效。 | 全部 |
### 檢視金鑰和註腳
**全部** - 開發套件提供的所有 HTTP 用戶端 –`UrlConnectionHttpClient`、`ApacheHttpClient`、`NettyNioAsyncHttpClient`、`AwsCrtAsyncHttpClient`。
**Netty** - Netty 型 HTTP 用戶端 (`NettyNioAsyncHttpClient`)。
**CRT** - AWS CRT 型 HTTP 用戶端 (`AwsCrtHttpClient` 和 `AwsCrtAsyncHttpClient`)。
1查詢的環境變數，無論是 `HTTP_PROXY`還是 `HTTPS_PROXY`，取決於用戶端 中的配置設定`ProxyConfiguration`。預設方案為 HTTP。下列程式碼片段說明如何將配置變更為用於環境變數解析的 HTTPS。
```
SdkHttpClient httpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.build())
.build();
```
2 `NO_PROXY`環境變數支援主機名稱之間的混合 "\$1" 和 "，" 分隔符號。主機名稱可能包含「\$1」萬用字元。
## 使用設定的組合
您可以在程式碼、系統屬性和環境變數中使用 HTTP 代理設定的組合。
**Example – 系統屬性和程式碼提供的組態**
```
// Command line with the proxy password set as a system property.
$ java -Dhttp.proxyPassword=SYS_PROP_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();
```
SDK 會解析下列代理設定。
```
Host = localhost
Port = 1234
Password = SYS_PROP_password
UserName = username
Non ProxyHost = null
```
**Example – 同時提供系統屬性和環境變數**
每個 HTTP 用戶端的`ProxyConfiguration`建置器都提供名為 `useSystemPropertyValues`和 的設定`useEnvironmentVariablesValues`。根據預設，這兩個設定都是 `true`。當 時`true`，軟體開發套件會自動將系統屬性或環境變數中的值用於`ProxyConfiguration`建置器未提供的選項。
系統屬性優先於環境變數。如果找到 HTTP 代理系統屬性，軟體開發套件會從系統屬性擷取***所有***值，而從環境變數擷取所有值。如果您想要優先考慮環境變數而非系統屬性，請將 `useSystemPropertyValues`設定為 `false`。
在此範例中，下列設定可供執行時間使用：
```
// System properties
http.proxyHost=SYS_PROP_HOST.com
http.proxyPort=2222
http.password=SYS_PROP_PASSWORD
http.user=SYS_PROP_USER
// Environment variables
HTTP_PROXY="http://EnvironmentUser:EnvironmentPassword@ENV_VAR_HOST:3333"
NO_PROXY="environmentnonproxy.host,environmentnonproxy2.host:1234"
```
使用下列其中一個陳述式建立服務用戶端。沒有任何陳述式會明確設定代理設定。
```
DynamoDbClient client = DynamoDbClient.create();
DynamoDbClient client = DynamoDbClient.builder().build();
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.build())
.build())
.build();
```
開發套件會解析下列代理設定：
```
Host = SYS_PROP_HOST.com
Port = 2222
Password = SYS_PROP_PASSWORD
UserName = SYS_PROP_USER
Non ProxyHost = null
```
由於服務用戶端具有預設代理設定，因此 SDK 會搜尋系統屬性，然後搜尋環境變數。由於系統屬性設定優先於環境變數，因此 SDK 只會使用系統屬性。
如果系統屬性的使用變更為 `false`，如下列程式碼所示，開發套件只會解析環境變數。
```
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build())
.build();
```
使用 HTTP 解析的代理設定如下：
```
Host = ENV_VAR_HOST
Port = 3333
Password = EnvironmentPassword
UserName = EnvironmentUser
Non ProxyHost = environmentnonproxy.host, environmentnonproxy2.host:1234
```
# 設定 Apache 5.x 型 HTTP 用戶端
## 存取 Apache5HttpClient
若要使用 `Apache5HttpClient`，您必須在 上新增相依性，**apache5-client**並在您的服務用戶端`Apache5HttpClient`上明確設定 。
```
software.amazon.awssdk
bom
2.41.0*
pom
import
software.amazon.awssdk
s3
software.amazon.awssdk
apache5-client
```
\$1將紅色顯示的版本取代為您要使用的 Java 開發套件版本。尋找 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 的最新資訊。
### 使用和設定 `Apache5HttpClient`
您可以設定 執行個體`Apache5HttpClient`以及建置服務用戶端，也可以設定單一執行個體以在多個服務用戶端之間共用。
透過任一方法，您可以使用 [Apache5HttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.Builder.html) 來設定 Apache 5 型 HTTP 用戶端的屬性。
#### 最佳實務：將 Apache5HttpClient 執行個體專用於服務用戶端
如果您需要設定 的執行個體`Apache5HttpClient`，我們建議您建置專用`Apache5HttpClient`執行個體。您可以使用服務用戶端建置器的 httpClientBuilder 方法來執行此操作。如此一來，HTTP 用戶端的生命週期由 SDK 管理，這有助於避免在`Apache5HttpClient`執行個體不再需要時關閉時造成潛在的記憶體流失。
下列範例會建立 S3Client，並使用 `Apache5HttpClient` maxConnections 和 connectionTimeout 值設定 的內嵌執行個體。HTTP 執行個體是使用 的 `httpClientBuilder`方法建立。 `S3Client.Builder`
**匯入**
```
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(Apache5HttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
)
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
#### 替代方法：共用`Apache5HttpClient`執行個體
為了協助降低應用程式的資源和記憶體用量，您可以設定 ，`Apache5HttpClient`並在多個服務用戶端之間共用。HTTP 連線集區將共用，這會降低資源用量。
**注意**
共用`Apache5HttpClient`執行個體時，您必須在準備好進行處置時將其關閉。當服務用戶端關閉時，軟體開發套件不會關閉執行個體。
下列範例會設定兩個服務用戶端所使用的 Apache 型 HTTP 用戶端。設定的`ApacheHttpClient`執行個體會傳遞至每個建置器的 httpClient 方法。當不再需要服務用戶端和 HTTP 用戶端時，程式碼會明確關閉它們。程式碼最後會關閉 HTTP 用戶端。
**匯入**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
SdkHttpClient apache5HttpClient = Apache5HttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apache5HttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apache5HttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apache5HttpClient.close(); // Explicitly close apache5HttpClient.
```