AWS SDK for Java 2.x を使用した AWS のサービス リクエストの実行

サービスクライアントを使用したリクエストの実行

「SDK の設定」の手順を完了し、サービスクライアントを設定する方法を理解すると、Amazon S3、Amazon DynamoDB、AWS Identity and Access Management、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 のサービスクライアントはスレッドセーフです。最高のパフォーマンスを得るには、長期間使用するオブジェクトとしてこれらを処理します。各クライアントには、クライアントがガーベージコレクションの対象になった場合にリリースされる独自の接続プールリソースを備えています。

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

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

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

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

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

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

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

サービスクライアントの設定方法の詳細については、「外部でのクライアントの設定」および「コードでのクライアント設定」を参照してください。

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

ベストプラクティスとして、アプリケーションの存続期間中の複数の 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 は、リクエストを作成してインスタンスに渡すのではなく、リクエストの作成に使用できる Fluent 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 インスタンスを指定して、設定を上書きできます。クライアント設定を上書きするために使用できるメソッドには、次のようなものがあります。

• apiCallAttemptTimeout

• apiCallTimeout

• credentialProvider

• compressionConfiguration

• putHeader

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

S3Client s3Client = S3Client.create();

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

Standard API

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

GetObjectRequest request = GetObjectRequest.builder()
    .bucket("amzn-s3-demo-bucket")
    .key("demo-key")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

Fluent API

s3Client.getObject(b -> b
        .bucket("amzn-s3-demo-bucket")
        .key("demo-key")
        .overrideConfiguration(c -> c
            .apiCallTimeout(Duration.ofSeconds(100L))
            .apiCallAttemptTimeout(Duration.ofSeconds(25L))),
    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());
}