サービスクライアントを使用する例外を処理するウェイターを使用する HTTP クライアントタイムアウト実行インターセプター追加情報

を使用する AWS SDK for Java 2.x

SDK のセットアップのステップを完了すると、Amazon S3、DynamoDB、Amazon EC2 などの AWS サービスにリクエストを行う準備が整います。

サービスクライアントを使用する

サービスクライアントを作成する

にリクエストを行うには AWS のサービス、まず静的ファクトリメソッドを使用して、そのサービスのサービスクライアントをインスタンス化する必要がありますbuilder()。builder() メソッドは、サービスクライアントをカスタマイズできる builder オブジェクトを返します。fluent setter メソッドでは builder オブジェクトが返るため、利便性とコードの可読性を高めるためにメソッドの呼び出しをチェーンすることができます。必要なプロパティを設定した後、build() メソッドを呼び出してクライアントを作成します。

例として、以下のコードスニペットは、Ec2Client オブジェクトを Amazon EC2 のサービスクライアントとしてインスタンス化します。


Region region = Region.US_WEST_2;
Ec2Client ec2Client = Ec2Client.builder()
        .region(region)
        .build();

注記

SDK のサービスクライアントはスレッドセーフです。最高のパフォーマンスを得るには、長期間使用するオブジェクトとしてこれらを処理します。各クライアントには、クライアントがガーベージコレクションの対象になった場合にリリースされる独自の接続プールリソースを備えています。

サービスクライアントオブジェクトはイミュータブルであるため、リクエストを実行する各サービスについて、または同じサービスにリクエストを実行するために異なる設定を使用する場合は、新しいクライアントを作成する必要があります。

サービスクライアントビルダーRegionでを指定することは、すべての AWS サービスに必須ではありませんが、アプリケーションで実行する API コールのリージョンを設定するのがベストプラクティスです。詳細については、「AWS リージョンの選択」を参照してください。

デフォルトのクライアント設定

このクライアントビルダーには、create() という名前の別のファクトリメソッドがあります。このメソッドでは、サービスクライアントがデフォルト設定で作成されます。デフォルトのプロバイダーチェーンを使用して認証情報と AWS リージョンをロードします。アプリケーションを実行している環境から認証情報またはリージョンを決定できない場合、create の呼び出しは失敗します。SDK が認証情報および使用するリージョンを決定する方法の詳細については、「認証情報の使用」および「リージョンの選択」を参照してください。

例えば、以下のコードスニペットは、DynamoDbClient オブジェクトを Amazon DynamoDB のサービスクライアントとしてインスタンス化します。


DynamoDbClient dynamoDbClient = DynamoDbClient.create();

サービスクライアントを設定する

サービスクライアントの設定をカスタマイズするには、builder() ファクトリーメソッドのセッターを使用します。便宜上、より読みやすいコードを作成するために、メソッドをつなぎ合わせて複数の構成オプションを設定します。

以下の例は、複数のカスタム設定で構成された S3Client を示しています。


ClientOverrideConfiguration clientOverrideConfiguration =
    ClientOverrideConfiguration.builder()
                    .apiCallAttemptTimeout(Duration.ofSeconds(1))
                    .retryPolicy(RetryPolicy.builder().numRetries(10).build())
                    .addMetricPublisher(CloudWatchMetricPublisher.create())
                    .build();

Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
                    .region(region)
                    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
                    .overrideConfiguration(clientOverrideConfiguration)
                    .httpClientBuilder(ApacheHttpClient.builder()
                        .proxyConfiguration(proxyConfig.build(ProxyConfiguration.builder()))
                        .build())
                    .build();

リクエストを発行する

サービスクライアントを使用して、対応するにリクエストを行います AWS のサービス。

例えば、このコードスニペットは、RunInstancesRequest オブジェクトを作成して新しい Amazon EC2 インスタンスを作成する方法を示しています。


// Create the request by using the fluid setter methods of the request builder.
RunInstancesRequest runInstancesRequest = RunInstancesRequest.builder()
        .imageId(amiId)
        .instanceType(InstanceType.T1_MICRO)
        .maxCount(1)
        .minCount(1)
        .build();

// Use the configured request with the service client.
RunInstancesResponse response = ec2Client.runInstances(runInstancesRequest);

SDK は、リクエストを作成してインスタンスに渡すのではなく、リクエストの作成に使用できるビルダーを備えています。ビルダーを使用すると、Java Lambda 式を使用してリクエストを「インライン」で作成できます。

次の例では、ビルダーを使用してリクエストを作成する runInstances メソッドのバージョンを使用して、前の例を書き換えています。


// Create the request by using a lambda expression.
RunInstancesResponse response = ec2.runInstances(r -> r
                .imageId(amiId)
                .instanceType(InstanceType.T1_MICRO)
                .maxCount(1)
                .minCount(1));

レスポンスを処理する

SDK は、ほとんどのサービスオペレーションのレスポンスオブジェクトを返します。コードは、必要に応じてレスポンスオブジェクト内の情報を処理できます。

例えば、次のコードスニペットは、前のリクエストの RunInstancesResponse オブジェクトで返された最初のインスタンス ID を出力します。


RunInstancesResponse runInstancesResponse = ec2Client.runInstances(runInstancesRequest);
System.out.println(runInstancesResponse.instances().get(0).instanceId());

ただし、すべてのオペレーションがサービス固有のデータを含むレスポンスオブジェクトを返すわけではありません。このような状況では、HTTP レスポンスのステータスをクエリして、オペレーションが成功したかどうかを確認できます。

例えば、次のスニペットのコードは、HTTP レスポンスをチェックして、Amazon Simple Email Service のDeleteContactListオペレーションが成功したかどうかを確認します。


SesV2Client sesv2Client = SesV2Client.create();

DeleteContactListRequest request = DeleteContactListRequest.builder()
    .contactListName("ExampleContactListName")
    .build();

DeleteContactListResponse response = sesv2Client.deleteContactList(request);
if (response.sdkHttpResponse().isSuccessful()) {
    System.out.println("Contact list deleted successfully");
} else {
    System.out.println("Failed to delete contact list. Status code: " + response.sdkHttpResponse().statusCode());
}

サービスクライアントを閉じる

ベストプラクティスとして、アプリケーションの存続期間中の複数の API サービス呼び出しにはサービスクライアントを使用する必要があります。ただし、サービスクライアントを 1 回だけ使用する必要がある場合や、サービスクライアントが不要になったら閉じます。

サービスクライアントが不要になったら、close() メソッドを呼び出してリソースを解放します。


ec2Client.close();

サービスクライアントを 1 回だけ使用する必要がある場合は、try-with-resources ステートメントでサービスクライアントをリソースとしてインスタンス化できます。サービスクライアントは Autoclosable インターフェースを実装するため、JDK はステートメントの最後で自動的に close() メソッドを呼び出します。

以下の例は、サービスクライアントを使用して 1 回限りのコールを実行する方法を示しています。を呼びStsClient出す AWS Security Token Service は、アカウント ID を返した後で閉じられます。


import software.amazon.awssdk.services.sts.StsClient;

String getAccountID() {
    try (StsClient stsClient = StsClient.create()) {
       return stsClient.getCallerIdentity().account();
    }
}

例外を処理する

SDK はランタイムの (またはチェックされていない) 例外を使用して、エラー処理をきめ細かく制御し、例外処理がアプリケーションに合わせてスケールされるようにします。

SdkServiceException、またはそのサブクラスの 1 つは、SDK がスローする最も一般的な例外フォームです。これらの例外は、 AWS のサービスからの応答を表します。また、ネットワーク接続の障害など、クライアント側 (つまり、開発環境やアプリケーション環境) で問題が発生した場合に生じる SdkClientException を処理することもできます。

このコードスニペットは、ファイルを Amazon S3にアップロードするときにサービスの例外を処理する 1 つの方法を示しています。このコード例は、クライアントとサーバーの両方の例外を受け取り、詳細をログに記録して、アプリケーションを存在させます。


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

try {

    PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .build();

    s3Client.putObject(putObjectRequest, RequestBody.fromString("SDK for Java test"));

} catch (S3Exception se) {
    System.err.println("Service exception thrown.");
    System.err.println(se.awsErrorDetails().errorMessage());
} catch (SdkClientExeption ce){
   System.err.println("Client exception thrown.");
   System.err.println(ce.getMessage());
} finally {
   System.exit(1);
}

詳細については、例外の処理を参照してください。

ウェイターを使用する

で新しいテーブルを作成したり、新しい Amazon S3 バケットを作成 DynamoDB したりするなど、処理に時間がかかるリクエストもあります。コードの実行を続行する前にリソースの準備ができているようにするには、Waiter を使用します。

例えば、このコードスニペットはに新しいテーブル (myTable」) を作成し DynamoDB、テーブルが ACTIVEステータスになるまで待機してから、レスポンスを出力します。


DynamoDbClient dynamoDbClient = DynamoDbClient.create();
DynamoDbWaiter dynamoDbWaiter = dynamoDbClient.waiter();

WaiterResponse<DescribeTableResponse> waiterResponse =
   dynamoDbWaiter.waitUntilTableExists(r -> r.tableName("myTable"));

waiterResponse.matched().response().ifPresent(System.out::println);

詳細については、ウェイターの使用を参照してください。

HTTP クライアント

AWS SDK for Javaを使用して構築するアプリケーションで、HTTP クライアントのデフォルト設定を変更できます。HTTP クライアントと設定を構成する方法については、HTTP 設定を参照してください。

タイムアウト

apiCallTimeout およびのapiCallAttemptTimeoutセッターを使用して、各サービスクライアントのタイムアウトを設定できますClientOverrideConfiguration.Builder。apiCallTimeout の設定は、クライアントが API コールの実行を完了するまでの猶予時間です。apiCallAttemptTimeout 設定は、各 HTTP リクエスト (再試行) が完了してからあきらめるまでの待機時間です。

次の例では、S3 クライアントの両方のタイムアウトを設定します。


S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L))).
    build();

また、を設定し、 overrideConfigurationメソッドを使用してリクエストオブジェクトに提供することでAwsRequestOverrideConfiguration、リクエストレベルでタイムアウトを設定することもできます。

次の例では、同じタイムアウト設定を使用しますが、S3 PutObjectオペレーションのリクエストレベルで使用します。


S3Client basicS3Client = S3Client.create(); // Client with no timeout settings.

AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(105L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

basicS3Client.putObject(b -> b
        .bucket("DOC-EXAMPLE-BUCKET")
        .key("DOC-EXAMPLE_KEY")
        .overrideConfiguration(overrideConfiguration),
    RequestBody.fromString("test"));

実行インターセプター

リクエスト/応答のライフサイクルのさまざまな部分で、API リクエストと応答の実行をインターセプトするコードを記述できます。これにより、メトリクスの発行、実行中のリクエストの変更、リクエスト処理のデバッグ、例外の表示などを行うことができます。詳細については、 AWS SDK for Java 「 API リファレンス」の「 ExecutionInterceptorインターフェイス」を参照してください。

追加情報

上記のコードスニペットの完全な例については、「の使用 Amazon DynamoDB」、「の使用 Amazon EC2」、「の使用 Amazon S3」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

GraalVM Native Image プロジェクトを設定する

SDK への一時的な認証情報の提供