사용 AWS SDK for Java 2.x - AWS SDK for Java 2.x
서비스 작업예외 처리웨이터 사용하기HTTP 클라이언트시간 초과실행 인터셉터추가 정보

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

사용 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();
참고

SDK의 서비스 클라이언트는 스레드 세이프입니다. 최상의 성능을 위해 수명이 긴 객체로 처리합니다. 각 클라이언트마다 클라이언트에서 가비지가 수집될 때 릴리스되는 고유한 연결 풀 리소스가 있습니다.

서비스 클라이언트 객체는 변경할 수 없으므로 요청하는 각 서비스에 대해 또는 동일한 서비스에 대한 요청을 위해 다른 구성을 사용하려는 경우 새 클라이언트를 만들어야 합니다.

모든 AWS 서비스에 대해 서비스 클라이언트 Region 빌더에서 를 지정할 필요는 없지만 애플리케이션에서 수행하는 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 DeleteContactListService의 작업이 성공했는지 확인합니다.

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 서비스 호출에 서비스 클라이언트를 사용하는 것입니다. 하지만 일회용으로 사용할 서비스 클라이언트가 필요하거나 더 이상 필요 없는 서비스 클라이언트는 닫으세요.

리소스를 확보하는 데 서비스 클라이언트가 더 이상 필요하지 않을 때 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();
    }
}

예외 처리

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를 사용하세요.

예를 들어 다음 코드 스니펫은 에서 DynamoDB새 테이블 ('myTable') 을 만들고 테이블이 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및 설정자를 사용하여 각 서비스 클라이언트의 타임아웃을 구성할 수 있습니다. apiCallAttemptTimeoutClientOverrideConfiguration.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 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 인터페이스를 참조하십시오.

추가 정보