사용 AWS SDK for Java 2.x

SDK 설정의 단계를 완료하면 Amazon S3, DynamoDB, IAM, Amazon EC2 등과 같은 AWS 서비스에 요청할 준비가 된 것입니다.

서비스 작업

서비스 클라이언트 생성

에 요청하려면 먼저 정적 팩토리 메서드를 사용하여 해당 서비스의 서비스 클라이언트를 인스턴스화 AWS 서비스해야 합니다builder(). 이 builder() 메서드는 서비스 클라이언트를 사용자 지정할 수 있는 builder 객체를 반환합니다. 유용한 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 서비스 호출에 서비스 클라이언트를 사용하는 것입니다. 하지만 일회용으로 사용할 서비스 클라이언트가 필요하거나 더 이상 필요 없는 서비스 클라이언트는 닫으세요.

리소스를 확보하는 데 서비스 클라이언트가 더 이상 필요하지 않을 때 close() 메서드를 호출하세요.

ec2Client.close();

일회용으로 사용할 서비스 클라이언트가 필요한 경우 try-with-resources 문을 사용하여 서비스 클라이언트를 리소스로 인스턴스화할 수 있습니다. 서비스 클라이언트가 Autoclosable 인터페이스를 구현하므로 JDK는 명령문 끝에서 close() 메서드를 자동으로 호출합니다.

다음 예제에서는 서비스 클라이언트를 사용하여 일회성 호출을 실행하는 방법을 보여줍니다. 를 호출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를 제공합니다. 유창한 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();

대용량 파일을 다운로드하고 다운로드가 완료되기 전에 요청이 시간 초과되지 않도록 하려고 합니다. 이렇게 하려면 다음 코드와 같이 단일 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 또는 하위 클래스 중 하나는 SDK에서 발생하는 가장 일반적인 예외 형식입니다. 이러한 예외는 AWS 서비스의 응답을 나타냅니다. 네트워크 연결 실패 등 클라이언트 측(예: 개발 환경 또는 애플리케이션 환경)에 문제가 있을 때 발생하는 SdkClientException도 처리할 수 있습니다.

이 코드 조각은 파일을 Amazon S3에 업로드할 때 서비스 예외를 처리하는 한 가지 방법을 보여줍니다. 예제 코드는 클라이언트 및 서버 예외를 모두 포착하고, 세부 정보를 기록하고, 애플리케이션을 종료합니다.

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

를 구성AwsRequestOverrideConfiguration하고 overrideConfiguration 메서드를 사용하여 요청 객체에 제공하여 요청 수준에서 제한 시간을 설정할 수도 있습니다.

다음 예제에서는 동일한 제한 시간 설정을 사용하지만 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 인터페이스를 참조하세요.