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

SDK のセットアップのステップを完了すると、Amazon S3、DynamoDB、IAM、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();

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

このクライアントビルダーには、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();

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

ベストプラクティスとして、アプリケーションの存続期間中の複数の 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();
    }
}

リクエストを発行する

サービスクライアントを使用して、対応する にリクエストを行います 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 は、リクエストを作成してインスタンスを渡すのではなく、リクエストの作成に使用できる流暢な API を提供します。fluent API を使用すると、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));

リクエストを使用してクライアント設定を上書きする

サービスクライアントはイミュータブルですが、その設定の多くをリクエストレベルで上書きできます。リクエストを構築するときに、AwsRequestOverrideConfiguration インスタンスを指定して、オーバーライドされた設定を指定できます。クライアント設定を上書きするために使用できる方法には、次のようなものがあります。

リクエストでクライアント設定を上書きする例については、デフォルト設定を使用する次の S3 クライアントがあるとします。

S3Client s3Client = S3Client.create();

大きなファイルをダウンロードし、ダウンロードが完了する前にリクエストがタイムアウトしないようにします。これを行うには、次のコードに示すように、1 つのGetObjectリクエストのみのタイムアウト値を増やします。

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

GetObjectRequest request = GetObjectRequest.builder()
    .bucket("DOC-EXAMPLE-BUCKET")
    .key("DOC-EXAMPLE-KEY")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

レスポンスを処理する

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());
}

例外を処理する

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);
}

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

ウェイターを使用する

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

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

タイムアウトの設定

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 default 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インターフェイスを参照してください。