마이그레이션에 대한 단계별 설명(예제 포함)

이 섹션에서는 현재 SDK for Java v1.x를 사용하는 애플리케이션을 SDK for Java 2.x로 마이그레이션하기 위한 단계별 안내서를 제공합니다. 첫 번째 부분에서는 단계에 대한 개요와 마이그레이션의 세부 예제를 제공합니다.

여기에서 다루는 단계는 애플리케이션이 모델 기반 서비스 클라이언트를 사용하여 AWS 서비스를 호출하는 일반적인 사용 사례의 마이그레이션을 설명합니다. S3 Transfer Manager 또는 CloudFront 사전 서명과 같은 개괄적인 API를 사용하는 코드를 마이그레이션해야 하는 경우 AWS SDK for Java 1.x와 2.x의 차이점은 무엇인가요? 목차 아래의 섹션을 참조하세요.

여기에 설명된 접근 방식은 제안입니다. 다른 기법을 사용하고 IDE의 코드 편집 기능을 활용하여 동일한 결과를 얻을 수 있습니다.

단계 개요

1. 먼저 SDK for Java 2.x BOM을 추가합니다.

SDK for Java 2.x의 Maven BOM(Bill of Materials) 요소를 POM 파일에 추가하면 필요한 모든 v2 종속성이 동일한 버전인지 확인할 수 있습니다. POM에는 v1 및 v2 종속성이 모두 포함될 수 있습니다. 이렇게 하면 코드를 한 번에 모두 변경하는 대신 점진적으로 마이그레이션할 수 있습니다.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>bom</artifactId>
      <version>2.27.21</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

2. v1 클래스 가져오기 문에 대한 파일 검색

애플리케이션의 파일에서 v1 가져오기에 사용되는 SERVICE_ID를 스캔하면 사용된 고유한 SERVICE_ID를 확인할 수 있습니다. SERVICE_ID는 AWS 서비스의 짧고 고유한 이름입니다. 예를 들어 cognitoidentity는 Amazon Cognito 자격 증명의 SERVICE_ID입니다.

3. v1 가져오기 문에서 v2 Maven 종속성 확인

모든 고유한 v1 SERVICE_ID를 찾은 후 Maven artifactId 매핑에 대한 패키지 이름을 참조하여 v2 종속성에 해당하는 Maven 아티팩트를 확인할 수 있습니다.

4. POM 파일에 v2 종속성 요소 추가

3단계에서 확인한 종속성 요소로 Maven POM 파일을 업데이트합니다.

5. Java 파일에서 v1 클래스를 v2 클래스로 점진적으로 변경합니다.

v1 클래스를 v2 클래스로 대체할 때 생성자 대신 빌더를 사용하고 유용한 getter 및 setter를 사용하는 등 v2 API를 지원하는 데 필요한 변경 사항을 적용합니다.

6. POM에서 v1 Maven 종속성 제거 및 파일에서 v1 가져오기

v2 클래스를 사용하도록 코드를 마이그레이션한 후 파일에서 남은 v1 가져오기와 빌드 파일에서 모든 종속성을 제거합니다.

7. v2 API 개선 사항을 사용하도록 코드 리팩터링

코드가 성공적으로 컴파일되고 테스트를 통과하면 다른 HTTP 클라이언트 또는 페이지 매김 도구를 사용하여 코드를 단순화하는 등 v2 개선 사항을 활용할 수 있습니다. 이 단계는 선택 사항입니다.

마이그레이션 예제

이 예제에서는 SDK for Java v1을 사용하고 여러 AWS 서비스에 액세스하는 애플리케이션을 마이그레이션합니다. 5단계에서 다음 v1 메서드를 자세히 살펴봅니다. 이는 8개의 메서드가 포함된 클래스의 한 가지 메서드이며 애플리케이션에는 32개의 클래스가 있습니다.

import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesResult;
import com.amazonaws.services.ec2.model.Instance;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Reservation;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;
...
private static List<Instance> getRunningInstances(AmazonEC2Client ec2, List<String> instanceIds) {
    List<Instance> runningInstances = new ArrayList<>();
    try {
        DescribeInstancesRequest request = new DescribeInstancesRequest()
                .withInstanceIds(instanceIds);
        DescribeInstancesResult result;
        do {
            // DescribeInstancesResponse is a paginated response, so use tokens with multiple requests.
            result = ec2.describeInstances(request);
            request.setNextToken(result.getNextToken());   // Prepare request for next page.
            for (final Reservation r : result.getReservations()) {
                for (final Instance instance : r.getInstances()) {
                    LOGGER.info("Examining instanceId: "+ instance.getInstanceId());
                    // if instance is in a running state, add it to runningInstances list.
                    if (RUNNING_STATES.contains(instance.getState().getName())) {
                        runningInstances.add(instance);
                    }
                }
            }
        } while (result.getNextToken() != null);
    } catch (final AmazonEC2Exception exception) {
        // if instance isn't found, assume its terminated and continue.
        if (exception.getErrorCode().equals(NOT_FOUND_ERROR_CODE)) {
            LOGGER.info("Instance probably terminated; moving on.");
        } else {
            throw exception;
        }
    }
    return runningInstances;
}

1. v2 Maven BOM 추가

dependencyManagement 섹션의 다른 종속성과 함께 SDK for Java 2.x용 Maven BOM을 POM에 추가합니다. POM 파일에 SDK v1용 BOM이 있는 경우 지금은 그대로 둡니다. 이후 단계에서 제거됩니다.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.example</groupId>             <!--Existing dependency in POM. -->
      <artifactId>bom</artifactId>
      <version>1.3.4</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-java-sdk-bom</artifactId>  <!--Existing v1 BOM dependency. -->
      <version>1.11.1000</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
    <dependency>
      <groupId>software.amazon.awssdk</groupId>  <!--Add v2 BOM dependency. -->
      <artifactId>bom</artifactId>
      <version>2.27.21</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

2. v1 클래스 가져오기 문에 대한 파일 검색

애플리케이션의 코드를 검색하여 import com.amazonaws.services의 고유한 발생을 찾습니다. 이를 통해 프로젝트에서 사용하는 v1 종속성을 확인할 수 있습니다. 애플리케이션에 v1 종속성이 나열된 Maven POM 파일이 있는 경우 이 정보를 대신 사용할 수 있습니다.

이 예제에서는 ripgrep(rg) 명령을 사용하여 코드 베이스를 검색합니다.

코드 베이스의 루트에서 다음 ripgrep 명령을 실행합니다. ripgrep가 가져오기 문을 찾은 후 cut, sort 및 uniq 명령으로 파이프 처리되어 SERVICE_ID를 격리합니다.

rg --no-filename 'import\s+com\.amazonaws\.services' | cut -d '.' -f 4 | sort | uniq

이 애플리케이션의 경우 다음 SERVICE_ID가 콘솔에 로그됩니다.

autoscaling
cloudformation
ec2
identitymanagement

이는 import 문에 사용된 다음 패키지 이름 각각이 한 번 이상 발생했음을 나타냅니다. 이 목적에 따라 개별 클래스 이름은 중요하지 않습니다. 사용되는 SERVICE_ID를 찾기만 하면 됩니다.

com.amazonaws.services.autoscaling.*
com.amazonaws.services.cloudformation.*
com.amazonaws.services.ec2.*
com.amazonaws.services.identitymanagement.*

3. v1 가져오기 문에서 v2 Maven 종속성 확인

2단계에서 격리한 v1용 SERVICE_ID를 예로 들면 autoscaling 및 cloudformation은 대부분 동일한 v2 SERVICE_ID에 매핑할 수 있습니다. v2 Maven artifactId는 대부분의 경우 SERVICE_ID와 일치하므로 POM 파일에 종속성 블록을 추가하는 데 필요한 정보가 포함됩니다.

다음 테이블은 v2 종속성을 확인하는 방법을 보여줍니다.

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>ec2</artifactId>
</dependency>

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>autoscaling</artifactId>
</dependency>

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>cloudformation</artifactId>
</dependency>

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>iam</artifactId>
</dependency>

* iam 매핑에 대한 identitymanagement는 SERVICE_ID가 버전 간에 다른 예외입니다. Maven 또는 Gradle이 v2 종속성을 해결할 수 없는 경우 Maven artifactId 매핑에 대한 패키지 이름 예외는 섹션을 참조하세요.

4. POM 파일에 v2 종속성 요소 추가

3단계에서는 POM 파일에 추가해야 하는 4개의 종속성 블록을 확인했습니다. 1단계에서 BOM을 지정했으므로 버전을 추가할 필요가 없습니다. 가져오기가 추가되면 POM 파일에 다음과 같은 종속성 요소가 포함됩니다.

    ...
  <dependencies>
    ...
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>autoscaling</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>iam</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>cloudformation</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>ec2</artifactId>
    </dependency>
    ...
  </dependencies>
    ...

5. Java 파일에서 v1 클래스를 v2 클래스로 점진적으로 변경합니다.

마이그레이션하는 메서드에서 다음을 확인합니다.

import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesResult;
import com.amazonaws.services.ec2.model.Instance;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Reservation;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;
...
private static List<Instance> getRunningInstances(AmazonEC2Client ec2, List<String> instanceIds)
    List<Instance> runningInstances = new ArrayList<>();
    try {
        DescribeInstancesRequest request = new DescribeInstancesRequest()
                .withInstanceIds(instanceIds);
        DescribeInstancesResult result;
        do {
            // DescribeInstancesResponse is a paginated response, so use tokens with multiple re
            result = ec2.describeInstances(request);
            request.setNextToken(result.getNextToken());   // Prepare request for next page.
            for (final Reservation r : result.getReservations()) {
                for (final Instance instance : r.getInstances()) {
                    LOGGER.info("Examining instanceId: "+ instance.getInstanceId());
                    // if instance is in a running state, add it to runningInstances list.
                    if (RUNNING_STATES.contains(instance.getState().getName())) {
                        runningInstances.add(instance);
                    }
                }
            }
        } while (result.getNextToken() != null);
    } catch (final AmazonEC2Exception exception) {
        // if instance isn't found, assume its terminated and continue.
        if (exception.getErrorCode().equals(NOT_FOUND_ERROR_CODE)) {
            LOGGER.info("Instance probably terminated; moving on.");
        } else {
            throw exception;
        }
    }
    return runningInstances;
}
...

목표는 모든 v1 가져오기를 v2 가져오기로 대체하는 것입니다. 한 번에 하나의 클래스를 진행합니다.

a. 가져오기 문 또는 클래스 이름 교체

describeRunningInstances 메서드의 첫 번째 파라미터는 v1 AmazonEC2Client 인스턴스입니다. 다음 중 하나를 수행합니다.

b. v1 모델 클래스를 v2와 동등한 클레스로 교체

v2 Ec2Client를 변경한 후 IDE를 사용하면 다음 문에 컴파일 오류가 표시됩니다.

                    result = ec2.describeInstances(request);

컴파일 오류는 v1의 DescribeInstancesRequest 인스턴스를 v2 Ec2Client describeInstances 메서드의 파라미터로 사용하여 발생합니다. 수정하려면 다음의 대체 또는 가져오기 문을 만듭니다.

import com.amazonaws.services.ec2.model.DescribeInstancesRequest

import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest

c. v1 생성자를 v2 빌더로 변경합니다.

v2 클래스에 생성자가 없기 때문에 컴파일 오류가 계속 표시됩니다. 수정하려면 다음 변경 사항을 적용합니다.

final DescribeInstancesRequest request = new DescribeInstancesRequest()
        .withInstanceIds(instanceIdsCopy);

final DescribeInstancesRequest request = DescribeInstancesRequest.builder()
        .instanceIds(instanceIdsCopy)
        .build();

d. v1 *Result 응답 객체를 v2 *Response에 상응하는 객체로 교체

v1과 v2의 일관된 차이점은 v2의 모든 응답 객체가 *Result 대신 *Response로 끝나는 것입니다. v1 DescribeInstancesResult 가져오기를 v2 가져오기인 DescribeInstancesResponse로 교체합니다.

d. API 변경 사항 적용

다음 문은 몇 가지 변경 사항이 필요합니다.

request.setNextToken(result.getNextToken());

v2에서 setter 메서드는 set를 사용하거나 prefix와 함께 사용하지 않습니다. 또한 접두사가 get인 getter 메서드는 SDK for Java 2.x에서 삭제됩니다.

request 인스턴스 등의 모델 클래스는 v2에서 변경할 수 없으므로 빌더로 새 DescribeInstancesRequest를 만들어야 합니다.

v2에서 문은 다음과 같습니다.

request = DescribeInstancesRequest.builder()
        .nextToken(result.nextToken())
        .build();

d. 메서드가 v2 클래스로 컴파일될 때까지 반복합니다.

나머지 코드를 계속 진행합니다. v1 가져오기를 v2 가져오기로 교체하고 컴파일 오류를 수정합니다. v2 API 참조 및 필요에 따라 다른 참조를 참고합니다.

이 단일 메서드를 마이그레이션하면 다음의 v2 코드가 포함됩니다.

import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;

import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.Reservation;
...
private static List<Instance> getRunningInstances(Ec2Client ec2, List<String> instanceIds) {
    List<Instance> runningInstances = new ArrayList<>();
        try {
            DescribeInstancesRequest request = DescribeInstancesRequest.builder()
                    .instanceIds(instanceIds)
                    .build();
            DescribeInstancesResponse result;
            do {
                // DescribeInstancesResponse is a paginated response, so use tokens with multiple re
                result = ec2.describeInstances(request);
                request = DescribeInstancesRequest.builder()   // Prepare request for next page.
                        .nextToken(result.nextToken())
                        .build();
                for (final Reservation r : result.reservations()) {
                    for (final Instance instance : r.instances()) {
                        // if instance is in a running state, add it to runningInstances list.
                        if (RUNNING_STATES.contains(instance.state().nameAsString())) {
                            runningInstances.add(instance);
                        }
                    }
                }
            } while (result.nextToken() != null);
        } catch (final Ec2Exception exception) {
            // if instance isn't found, assume its terminated and continue.
            if (exception.awsErrorDetails().errorCode().equals(NOT_FOUND_ERROR_CODE)) {
                    LOGGER.info("Instance probably terminated; moving on.");
            } else {
                throw exception;
            }
        }
        return runningInstances;
    }
...

8가지 메서드로 Java 파일의 단일 메서드를 마이그레이션하기 때문에 파일을 작업할 때 v1과 v2 가져오기가 혼합되어 있습니다. 단계를 수행할 때 마지막 6개의 가져오기 문을 추가했습니다.

모든 코드를 마이그레이션하면 더 이상 v1 가져오기 문이 없습니다.

6. POM에서 v1 Maven 종속성 제거 및 파일에서 v1 가져오기

파일의 모든 v1 코드를 마이그레이션하면 다음과 같은 v2 SDK 가져오기 문이 있습니다.

import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.regions.ServiceMetadata;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.CreateTagsRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.InstanceStateName;
import software.amazon.awssdk.services.ec2.model.Reservation;
import software.amazon.awssdk.services.ec2.model.Tag;
import software.amazon.awssdk.services.ec2.model.TerminateInstancesRequest;

애플리케이션의 모든 파일을 마이그레이션하면 더 이상 POM 파일에 v1 종속성이 필요하지 않습니다. 모든 v1 종속성 블록을 사용하는 경우 dependencyManagement 섹션에서 v1 BOM을 제거합니다.

7. v2 API 개선 사항을 사용하도록 코드 리팩터링

마이그레이션 중인 코드 조각의 경우 v2 페이지 매김 도구를 필요에 따라 사용하고 SDK가 더 많은 데이터에 대한 토큰 기반 요청을 관리하도록 할 수 있습니다.

전체 do절을 다음으로 교체할 수 있습니다.

                DescribeInstancesIterable responses = ec2.describeInstancesPaginator(request);

                responses.reservations().stream()
                        .forEach(reservation -> reservation.instances()
                                .forEach(instance -> {
                                    if (RUNNING_STATES.contains(instance.state().nameAsString())) {
                                        runningInstances.put(instance.instanceId(), instance);
                                    }
                                }));

Maven artifactId 매핑에 대한 패키지 이름

Maven 또는 Gradle 프로젝트를 SDK for Java의 v1에서 v2로 마이그레이션할 때 빌드 파일에 추가할 종속성을 파악해야 합니다. 마이그레이션에 대한 단계별 설명(예제 포함)(3단계)에 설명된 접근 방식은 가져오기 문의 패키지 이름을 시작점으로 사용하여 빌드 파일에 추가할 종속성(artifactId)을 결정합니다.

이 주제의 정보를 사용하여 v1 패키지 이름을 v2 artifactId로 매핑합니다.

패키지 이름 및 Maven artifactId에 사용되는 일반적인 이름 지정 규칙

다음 테이블에는 SDK가 주어진 SERVICE_ID에 사용하는 일반적인 이름 지정 규칙이 나와 있습니다. SERVICE_ID는 AWS 서비스의 고유 식별자입니다. 예를 들어 Amazon S3 서비스의 SERVICE_ID는 s3이고 cognitoidentity는 Amazon Cognito 자격 증명의 SERVICE_ID입니다.

SERVICE_ID 차이점

v1 내

경우에 따라 SERVICE_ID는 패키지 이름과 동일한 서비스의 artifactId 간에 다릅니다. 예를 들어 다음 테이블의 CloudWatch Metrics 행은 metrics이 패키지 이름의 SERVICE_ID이지만 cloudwatchmetrics은 artifactId의 SERVICE_ID임을 보여줍니다.

v2 내

패키지 이름 및 artifactId에 사용되는 SERVICE_ID에는 차이가 없습니다.

v1 및 v2 차이

대부분의 서비스에서 v2의 SERVICE_ID는 패키지 이름과 artifactId 모두에서 v1의 SERVICE_ID와 동일합니다. 이전 테이블과 같이 cognitoedentity SERVICE_ID를 예로 들 수 있습니다. 그러나 다음 테이블과 같이 일부 SERVICE_ID는 SDK 간에 다릅니다.

v1 열 중 하나에 있는 boldface SERVICE_ID는 v2에 사용된 SERVICE_ID와 다르다는 것을 나타냅니다.