예제가 포함된 마이그레이션 step-by-step 지침

이 섹션에서는 현재 Java v1.xSDK용 를 사용하는 애플리케이션을 Java 2.xSDK용 로 마이그레이션하는 step-by-step 지침을 제공합니다. 첫 번째 부분에서는 단계에 대한 개요와 마이그레이션의 세부 예제를 보여줍니다.

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

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

단계 개요

1. Java 2.xSDK용 를 추가하여 시작합니다. BOM

Java 2.xSDK용 에 대한 MavenBOM(자재 명세서) 요소를 POM 파일에 추가하면 필요한 모든 v2 종속성이 동일한 버전인지 확인할 수 있습니다. 에는 v1 및 v2 종속성이 모두 포함될 POM 수 있습니다. 이렇게 하면 코드를 한 번에 모두 변경하지 않고 점진적으로 마이그레이션할 수 있습니다.

<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_IDs에 대해 애플리케이션의 파일을 스캔하면 고유한 SERVICE_IDs가 사용됩니다. SERVICE_ID는 의 짧고 고유한 이름입니다 AWS 서비스. 예를 들어 Amazon Cognito Identity의 SERVICE_IDcognitoidentity가 있습니다.

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

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

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

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

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

v1 클래스를 v2 클래스로 대체할 때 구성자 대신 빌더를 사용하고 유창한 게터와 세터를 사용하는 API 등 v2를 지원하는 데 필요한 변경을 수행합니다.

6. 에서 v1 Maven 종속성을 제거하고 파일에서 POM v1 가져오기를 제거합니다.

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

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

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

마이그레이션 예제

이 예제에서는 for Java v1SDK을 사용하고 여러 에 액세스하는 애플리케이션을 마이그레이션합니다 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 섹션의 다른 종속 항목을 POM 따라 Java 2.xBOMSDK용 의 Maven을 에 추가합니다. POM 파일에 의 v1에 BOM 대한 가 있는 경우 지금 그대로 SDK둡니다. 이후 단계에서 제거됩니다.

<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_를 격리합니다IDs.

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

이 애플리케이션의 경우 다음 SERVICE_IDs가 콘솔에 기록됩니다.

autoscaling
cloudformation
ec2
identitymanagement

이는 import 문에 사용된 다음 패키지 이름 각각이 하나 이상 발생했음을 나타냅니다. 4가지 목적, 개별 클래스 이름은 중요하지 않습니다. 사용되는 SERVICE_IDs만 찾으면 됩니다.

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

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

2단계에서 분리한 v1의 SERVICE_IDs, 예를 들어 autoscaling 및 cloudformation는 대부분 동일한 v2 SERVICE_ID에 매핑할 수 있습니다. v2 Maven은 대부분의 경우 SERVICE_ID와 artifactId 일치하므로 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>

* identitymanagement 대상 iam 매핑은 버전마다 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의 인스턴스를 v2 Ec2Client describeInstances 메서드의 파라미터DescribeInstancesRequest로 사용하여 발생합니다. 수정하려면 다음 대체 또는 가져오기 문을 만듭니다.

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의 모든 응답 객체가 *Response 대신 로 종료*Result된다는 것입니다. v1 DescribeInstancesResult 가져오기를 v2 가져오기로 바꿉니다DescribeInstancesResponse.

d. API 변경하기

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

request.setNextToken(result.getNextToken());

v2에서 설정자 메서드는 set 또는 를 와 함께 사용하지 않습니다prefix. 접두사가 인 Getter 메서드get도 Java 2.xSDK용 에서 삭제됩니다.

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. 에서 v1 Maven 종속성 제거 POM 및 파일에서 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 종속성이 더 이상 필요하지 않습니다. 를 사용하는 경우 dependencyManagement 섹션에서 v1을 제거하고 모든 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 프로젝트를 JavaSDK용 의 v1에서 v2로 마이그레이션할 때 빌드 파일에 추가할 종속성을 파악해야 합니다. 예제가 포함된 마이그레이션 step-by-step 지침 (3단계)에 설명된 접근 방식은 가져오기 명령문의 패키지 이름을 시작점으로 사용하여 빌드 파일에 추가할 종속성(로artifactIds)을 결정합니다.

이 주제의 정보를 사용하여 v1 패키지 이름을 v2 에 매핑할 수 있습니다artifactIds.

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

다음 표에는 가 지정된 SERVICE_ID에 SDKs 사용하는 일반적인 이름 지정 규칙이 나와 있습니다. SERVICE_ID는 의 고유 식별자입니다 AWS 서비스. 예를 들어 Amazon S3 서비스의 SERVICE_ID는 s3 이고 cognitoidentity는 Amazon Cognito Identity의 SERVICE_ID입니다.

SERVICE_ID 차이

v1 내

경우에 따라 SERVICE_ID는 패키지 이름과 의 동일한 서비스에 artifactId 대해 다릅니다. 예를 들어 다음 표의 CloudWatch 지표 행에는 metrics가 패키지 이름의 SERVICE_ID이지만 artifactId의 SERVICE_IDcloudwatchmetrics인 것으로 표시됩니다.

v2 내

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

v1과 v2 사이

대부분의 서비스의 경우 v2의 SERVICE_ID는 패키지 이름 및 모두에서 v1의 SERVICE_ID와 동일합니다artifactIds. 이 예제는 이전 표에 표시된 cognitoedentitySERVICE_ID입니다. 그러나 다음 표와 SDKs 같이 일부 SERVICE_IDs는 서로 다릅니다.

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