AWS SDK for Java 2.x でのクライアントエンドポイントの設定 - AWS SDK for Java 2.x
エンドポイント設定オプションコード内エンドポイント設定リクエストレベルのエンドポイント設定エンドポイントの外部設定設定の優先順位サービス固有のエンドポイント設定ベストプラクティス

AWS SDK for Java 2.x でのクライアントエンドポイントの設定

SDK for Java 2.x には、サービスエンドポイントを設定する複数の方法があります。エンドポイントは、SDK が AWS のサービス への API コールを行うために使用する URL です。デフォルトでは、SDK は設定した AWS リージョン に基づいて、各サービスに適したエンドポイントを自動的に決定します。ただし、これらのエンドポイントをカスタマイズまたは上書きする必要がある場合があります。

  • ローカルまたはサードパーティーのサービス実装 (LocalStack など) の使用

  • プロキシまたは VPC エンドポイントを介した AWS のサービス への接続

  • ベータまたはプレリリースサービスエンドポイントに対するテスト

エンドポイント設定オプション

AWS SDK for Java 2.x には、エンドポイントを設定するいくつかの方法があります。

  • サービスクライアントビルダーを使用したコード内設定

  • 環境変数を使用した外部設定

  • JVM システムプロパティを使用した外部設定

  • 共有 AWS 設定ファイルを使用した外部設定

コード内エンドポイント設定

の使用endpointOverride

エンドポイントを設定する最も直接的な方法は、サービスクライアントビルダーで endpointOverride メソッドを使用することです。このメソッドは、カスタムエンドポイント URL を表す URI オブジェクトを受け入れます。

例 Amazon S3 クライアントのカスタムエンドポイントの設定

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .endpointOverride(URI.create("https://my-custom-s3-endpoint.example.com"))
        .build();

endpointOverride を使用する場合、エンドポイントが明示的に設定されている場合も、クライアントのリージョンを指定する必要があります。リージョンは、リクエストの署名に使用されます。

エンドポイント検出

一部の AWS のサービス は、SDK が最適なエンドポイントを自動的に検出して使用できるエンドポイント検出をサポートしています。この機能は、サービスクライアントビルダーの endpointDiscoveryEnabled メソッドを使用して有効化または無効化できます。

例 DynamoDB クライアントのエンドポイント検出の有効化

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .region(Region.US_WEST_2)
        .endpointDiscoveryEnabled(true)
        .build();

リクエストレベルのエンドポイント設定

場合によっては、デフォルトのエンドポイントで他のリクエストに同じクライアントを使用しつつ、特定のリクエストのエンドポイントを上書きする必要があります。AWS SDK for Java 2.x は、リクエストの上書きによってこれをサポートします。

例 特定のリクエストのエンドポイントの上書き

import software.amazon.awssdk.core.SdkRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.http.SdkHttpRequest;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .build();

// Create a request
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
        .bucket("amzn-s3-demo-bucket")
        .key("my-key")
        .overrideConfiguration(c -> c.putHeader("Host", "custom-endpoint.example.com"))
        .build();

// Execute the request with the custom endpoint
s3.getObject(getObjectRequest);

リクエストレベルのエンドポイント上書きは制限されており、一部のサービスやシナリオでは機能しない場合があります。ほとんどの場合、クライアントレベルのエンドポイント設定を使用することをお勧めします。

エンドポイントの外部設定

環境変数の使用

環境変数を使用してエンドポイントを設定できます。SDK は、AWS_ENDPOINT_URL_[SERVICE] 形式の環境変数を使用したサービス固有のエンドポイント設定をサポートします。ここで、[SERVICE] は大文字のサービス識別子です。

例 環境変数を使用した S3 エンドポイントの設定

# For Linux/macOS
export AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com

# For Windows
set AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com

次の環境変数を使用して、グローバルエンドポイント URL のプレフィックスまたはサフィックスを設定することもできます。

  • AWS_ENDPOINT_URL - すべてのサービスのグローバルエンドポイントを設定します。

  • AWS_ENDPOINT_URL_PREFIX - すべてのサービスエンドポイントにプレフィックスを追加します。

  • AWS_ENDPOINT_URL_SUFFIX - すべてのサービスエンドポイントにサフィックスを追加します。

JVM システムプロパティの使用

JVM システムプロパティを使用してエンドポイントを設定することもできます。形式は環境変数と似ていますが、別の命名規則を使用します。

例 JVM システムプロパティを使用した S3 エンドポイントの設定

java -Daws.endpointUrl.s3=https://my-custom-s3-endpoint.example.com -jar your-application.jar

システムプロパティを使用したグローバルエンドポイント設定も可能です。

  • aws.endpointUrl - すべてのサービスのグローバルエンドポイントを設定します。

  • aws.endpointUrl.prefix - すべてのサービスエンドポイントにプレフィックスを追加します。

  • aws.endpointUrl.suffix - すべてのサービスエンドポイントにサフィックスを追加します。

共有 AWS 設定ファイルの使用

AWS SDK for Java 2.x は、共有 AWS 設定ファイルを介したエンドポイント設定もサポートします。設定ファイルは通常は ~/.aws/config (Linux/macOS) または %USERPROFILE%\.aws\config (Windows) にあります。詳細と例については、「AWS SDK およびツールリファレンスガイド」を参照してください。

設定の優先順位

複数のエンドポイント設定が存在する場合、SDK は次の優先順位 (上位から下位) に従います。

  1. リクエストレベルの上書き (該当する場合)

  2. endpointOverride を介したクライアントレベルの設定

  3. 環境変数

  4. JVM システムプロパティ

  5. 共有 AWS 設定ファイル

  6. 設定された AWS リージョン に基づくデフォルトのエンドポイント

サービス固有のエンドポイント設定

一部の AWS のサービス には、そのサービスに固有の追加のエンドポイント設定オプションがあります。ここにいくつか例を挙げます。

Amazon S3 エンドポイント設定

Amazon S3 は、 S3Configuration クラスを使用した複数のエンドポイント設定をサポートしています。

  • dualstackEnabled - IPv6 サポートを有効にします。

  • accelerateModeEnabled - S3 Transfer Acceleration を有効にします。

  • pathStyleAccessEnabled - 仮想ホスト形式の代わりにパス形式のアクセスを使用します。

  • useArnRegionEnabled - クロスリージョンリクエストに ARN のリージョンを使用します。

  • fipsModeEnabled - リクエストを FIPS 準拠のエンドポイントにルーティングします。

例 S3 固有エンドポイントオプションの設定

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .serviceConfiguration(S3Configuration.builder()
                .accelerateModeEnabled(true)
                .dualstackEnabled(true)
                .pathStyleAccessEnabled(false)
                .fipsModeEnabled(true)
                .build())
        .build();

DynamoDB エンドポイント設定

DynamoDB の場合、テストのためにエンドポイント検出を使用するか、DynamoDB local に接続できます。

例 DynamoDB local への接続

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import java.net.URI;

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .endpointOverride(URI.create("http://localhost:8000"))
        // The region is meaningless for DynamoDB local but required for the client builder.
        .region(Region.US_WEST_2)
        .build();

DynamoDB は、コードまたは外部設定を使用して設定できるアカウントベースのエンドポイントの使用もサポートしています。次の例は、クライアントの作成時にコードでアカウントベースのエンドポイントの使用を無効にする方法を示しています (デフォルト設定が推奨されます）。

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
    .region(Region.US_EAST_1)
    .accountIdEndpointMode(AccountIdEndpointMode.DISABLED)
    .build();

ベストプラクティス

AWS SDK for Java 2.x でエンドポイントを設定する場合は、次のベストプラクティスを考慮してください。

  • 環境固有のエンドポイントに外部設定を使用する — 環境変数、システムプロパティ、または環境 (開発、テスト、本番稼働) に応じて異なるエンドポイントの AWS 設定ファイルを使用します。

  • アプリケーション固有のエンドポイントにコード内設定を使用する — アプリケーションの設計に固有のエンドポイントには、クライアントビルダーの endpointOverride メソッドを使用します。

  • 常にリージョンを指定する — エンドポイントを上書きするときも、リクエスト署名に使用されるリージョンを常に指定します。

  • グローバルエンドポイントの上書きに注意する — グローバルエンドポイントの上書きを使用すると、意図しないサービスも含めたすべてのサービスに影響する可能性があります。

  • セキュリティへの影響を考慮する — カスタムエンドポイントを使用する場合は、特に本番環境のワークロードに対して、適切なセキュリティ対策が講じられていることを確認してください。