設定 AWS CRT型HTTP用戶端 - AWS SDK for Java 2.x
存取 AWS CRT型HTTP用戶端使用和設定 AWS CRT型HTTP用戶端將 AWS CRT型HTTP用戶端設定為預設值進階組態HTTP/2 支援Proxy 組態範例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定 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 用戶端是 S3AsyncClient 介面的實作，用於使用 Amazon S3 服務。它是以 Java 為基礎的S3AsyncClient介面實作的替代方案，並提供幾個優點。

雖然這兩個元件都使用 AWS Common Runtime 的程式庫，但 AWS CRT型HTTP用戶端不會使用 aws-c-s3 個程式庫，也不支援 S3 分段上傳API功能。相比之下， AWS CRT型 S3 用戶端的建置目的是支援 S3 分段上傳API功能。

存取 AWS CRT型HTTP用戶端

在使用 AWS CRT型HTTP用戶端之前，請將aws-crt-client成品至少為 2.22.0 版，新增至專案的相依性。

下列 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 中央儲存庫以取得最新版本 。

使用和設定 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;

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用戶端執行個體時，您必須在準備好進行處置時將其關閉。服務用戶端關閉時， 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;

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範例中， 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型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;

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或 TranscribeStreamingAsyncClient，請考慮NettyNioAsyncHttpClient改用 。

Proxy 組態範例

下列程式碼片段顯示ProxyConfiguration.Builder您使用 來設定程式碼中的代理設定。

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，且 只會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