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 ロードバランサー

SDK の AWS CRT ベースのコンポーネント

このトピックで説明している AWS CRT ベースの HTTP クライアントと AWS CRT ベースの S3 クライアントは、SDK の異なるコンポーネントです。

同期および非同期のAWS CRT ベースの HTTP クライアントは、SDK HTTP インターフェイスを実装したもので、一般的な HTTP 通信に使用されます。これらは SDK の他の同期 または 非同期の HTTP クライアントに代わるものですが、その他の利点もあります。

AWS CRT ベースの S3 クライアントは S3AsyncClient インターフェイスの実装であり、Amazon S3 サービスを利用するために使用されます。これは S3AsyncClient インターフェースの Java ベース実装に代わるもので、いくつかの利点があります。

どちらのコンポーネントも 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 ファイルをセットアップするには、次のいずれかのオプションを使用します。

注記

アプリケーションが AWS Lambda 関数で実行されている場合など、ランタイム依存関係のサイズを小さくする必要がある場合は、プラットフォーム固有の jar オプションを使用できます。

Uber-jar option

デフォルトでは、aws-crt-client は Linux、Windows、macOS など、複数のプラットフォームのバイナリを含む AWS CRT アーティファクトの uber-jar を使用します。

<project>
   <properties>
     <aws.sdk.java.version>2.29.10*</aws.sdk.java.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>

*赤で示されているバージョンを、使用する Java SDK のバージョンに置き換えてください。Maven Central で最新最新バージョンを見つけます。

Platform-specific jar option

Java ランタイムをプラットフォーム固有のバージョンの AWS CRT ライブラリに制限するには、Uber-jar オプションに次の変更を加えます。

  • SDK のaws-crt-client アーティファクトに exclusions 要素を追加します。この除外により、SDK が CRT AWS uber-jar を推移的に使用できないようにします。

  • 必要な特定の AWS CRT プラットフォームバージョンの依存関係要素を追加します。正しいバージョンを判断する方法については、以下の「AWS CRT アーティファクトのバージョンを判断する手順」を確認してください。

<project>
   <properties>
     <aws.sdk.java.version>2.29.101</aws.sdk.java.version>
  </properties>
   <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>software.amazon.awssdk</groupId>
                <artifactId>bom</artifactId>
                <version>${aws.sdk.java.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>aws-crt-client</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>software.amazon.awssdk.crt</groupId>
                    <artifactId>aws-crt</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.31.32</version>
            <classifier>linux-x86_643</classifier>
        </dependency>
    </dependencies>

1赤で示されているバージョンを、使用する Java SDK のバージョンに置き換えてください。Maven Central で最新最新バージョンを見つけます。

2Uber-jar オプションによって提供される software.amazon.awssdk.crt:aws-crt のバージョンを置き換えてください。以下の「AWS CRT アーティファクトのバージョンを判断する手順」を参照してください。

3classifier の値をお使いのプラットフォームの値に置き換えてください。使用可能な値のリストについては、AWS CRT for Java に関する GitHub ページを参照してください。

AWS CRT アーティファクトのバージョンを判断する手順

次の手順を使用して、使用している SDK for Java のバージョンと互換性のある AWS CRT アーティファクトのバージョンを確認します。

  1. Uber-jar オプションに示すように、 pom.xml ファイルを設定します。この設定により、デフォルトでどのバージョンの software.amazon.awssdk.crt:aws-crt が SDK に導入されているかを確認できます。

  2. プロジェクトのルート ( pom.xml ファイルと同じディレクトリ) で、次の Maven コマンドを実行します。

    mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt

    Maven は他のアクションを実行する場合がありますが、最後に SDK が推移的に使用する software.amazon.awssdk.crt:aws-crt 依存関係のコンソール出力が表示されます。次のスニペットは、SDK のバージョン 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

  3. コンソールが software.amazon.awssdk.crt:aws-crt アーティファクトに対して表示するバージョンを使用します。この場合、0.31.3 を pom.xml ファイルに追加します。

AWS CRT ベースの HTTP クライアントを使用および設定する

サービスクライアントを構築すると同時に AWS CRT ベースの HTTP クライアントを設定することも、単一インスタンスを複数のサービスクライアント間で共有するように設定することもできます。

どちらの方法でも、ビルダーを使用して AWS CRT ベースの HTTP クライアントインスタンスのプロパティを設定します。

ベストプラクティス: インスタンスをサービスクライアント専有にする

AWS CRT ベースの HTTP クライアントのインスタンスを設定する必要がある場合は、サービスクライアントと一緒にインスタンスを構築して専有することをお勧めします。これを行うには、サービスクライアントのビルダーの httpClientBuilder メソッドを使用します。この方法では、HTTP クライアントのライフサイクルが SDK によって管理されるため、不要になったときに AWS CRT ベースの HTTP クライアントインスタンスを閉じなかった場合にメモリリークが発生するのを防ぐことができます。

次の例では、S3 サービスクライアントを作成し、AWS CRT ベースの HTTP クライアントに connectionTimeout と maxConcurrency の値を設定します。

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 はインスタンスを閉じません。

次の例では、AWS CRT ベースの HTTP クライアントインスタンスに connectionTimeout と maxConcurrency の値を設定します。設定された 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 クライアントをデフォルトとして設定する

SDK が AWS CRT ベースの HTTP クライアントをサービスクライアントのデフォルト HTTP クライアントとして使用するように Maven ビルドファイルを設定できます。

そのためには、デフォルトの HTTP クライアント依存関係を持つ exclusions 要素を各サービスクライアントアーティファクトに追加します。

次の pom.xml の例では、SDK は S3 サービスに AWS CRT ベースの HTTP クライアントを使用しています。コード内のサービスクライアントが 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 central リポジトリにアクセスして、最新のバージョン値を確認します。

注記

1 つの pom.xml ファイル内で複数のサービスクライアントが宣言されている場合は、すべて exclusions XML 要素を必要とします。

Java システムプロパティを使用する

アプリケーションのデフォルト HTTP として AWS CRT ベースの 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 クライアントの接続のヘルス設定を構成できます。

次の例では、接続のヘルス設定と接続の最大アイドル時間を設定した AWS CRT ベースの HTTP クライアントインスタンスを使用する S3 サービスクライアントを作成します。

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 サポート

HTTP/2 プロトコルは、AWS CRT ベースの HTTP クライアントではまだサポートされていませんが、将来のリリースでサポートされる予定です。

それまでの間、KinesisAsyncClient や TranscribeStreamingAsyncClient などの HTTP/2 サポートを必要とするサービスクライアントを使用している場合は、代わりに 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 に設定する必要があります。スキームプロパティがコードで設定されていない場合、スキームのデフォルトは 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