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

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

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

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

サービスクライアントビルダーRegionで を指定することは、すべての AWS サービスに必須ではありませんが、アプリケーションで実行する 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 は、リクエストを作成してインスタンスを渡すのではなく、リクエストの作成に使用できる流暢な 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("DOC-EXAMPLE-BUCKET")
    .key("DOC-EXAMPLE-KEY")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

Fluent API

s3Client.getObject(b -> b
        .bucket("DOC-EXAMPLE-BUCKET")
        .key("DOC-EXAMPLE-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());
}