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

를 사용합니다. AWS SDK for Java 2.x

설정SDK의 단계를 완료한 후 Amazon S3, DynamoDB, , IAMAmazon EC2등과 같은 AWS 서비스에 요청할 준비가 되었습니다.

서비스 작업

서비스 클라이언트 생성

에 요청하려면 먼저 정적 팩토리 메서드인 를 사용하여 해당 서비스에 대한 서비스 클라이언트를 인스턴스화 AWS 서비스해야 합니다builder(). 이 builder() 메서드는 서비스 클라이언트를 사용자 지정할 수 있는 builder 객체를 반환합니다. 유용한 setter 메서드는 builder 객체를 반환해 읽기 쉽고 편리하도록 메서드 호출을 묶을 수 있게 도와줍니다. 원하는 속성을 구성한 후에는 build() 메서드를 호출하여 클라이언트를 생성할 수 있습니다.

예를 들어 다음 코드 조각은 Amazon 의 서비스 클라이언트로 Ec2Client 객체를 인스턴스화합니다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 인터페이스를 구현하므로 는 문 끝에 close() 메서드를 JDK 자동으로 호출합니다.

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

는 요청을 생성하고 인스턴스를 전달하는 대신 요청을 생성하는 데 사용할 수 API 있는 유창한 를 SDK 제공합니다. 유창한 를 사용하면 Java lambda 표현식을 사용하여 '인라인' 요청을 생성할 API 수 있습니다.

다음 예제에서는 빌더를 사용하여 요청을 생성하는 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 요청의 제한 시간 값을 늘립니다.

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

예외 처리

는 런타임(또는 선택하지 않은) 예외를 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')을 생성하고 테이블이 ACTIVE 상태가 될 때까지 DynamoDB기다린 다음 응답을 출력합니다.

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 요청 및 응답의 실행을 가로채는 코드를 작성할 수 있습니다. 이를 통해 지표 게시, 진행 중인 요청 수정, 요청 처리 디버그, 예외 보기 등의 작업을 수행할 수 있습니다. 자세한 내용은 참조의 ExecutionInterceptor 인터페이스를 참조하세요 AWS SDK for Java API.