ステップバイステップの移行手順

このセクションでは、現在 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 (部品表) 要素を 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 ID の 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 クラスに置き換えるときは、コンストラクタの代わりにビルダーを使用する、Fluent ゲッターやセッターを使用するなど、v2 API をサポートするために必要な変更を加えます。

6. POM から v1 Maven の依存関係を削除し、ファイルから v1 インポートを削除する

v2 クラスを使用するようにコードを移行したら、ファイルからの v1 の残りのインポートと、ビルドファイルからのすべての依存関係を削除します。

7. v2 API の拡張機能を使用するようにコードをリファクタリングする

コードが正常にコンパイルされてテストに合格したら、別の HTTP クライアントやページネーターを使用してコードを簡素化するなど、v2 の拡張機能を活用できます。これは任意の手順です。

移行の例

この例では、SDK for Java v1 を使用し、複数の AWS のサービス にアクセスするアプリケーションを移行します。ステップ 5 では、次の v1 メソッドについて詳しく説明します。これは、8 つのメソッドを含むクラスの 1 つのメソッドであり、アプリケーションには 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 を追加する

SDK for Java 2.x の Maven BOM を、 dependencyManagement セクションの他の依存関係とともに 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 ステートメントで次の各パッケージ名が少なくとも 1 回出現したことを示しています。今回の目的では、個々のクラス名は関係ありません。使用される 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>

* 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 インポートに置き換えることです。一度に 1 つのクラスずつ処理します。

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 では、セッターメソッドは set または prefix を使用しません。プレフィックスが get のゲッターメソッドも 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 ファイルの 1 つのメソッドを移行するため、ファイルを処理する際に 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 依存関係は必要ありません。使用している場合は、 dependencyManagement セクションから v1 BOM と、すべての v1 依存関係ブロックを削除します。

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) で説明されているアプローチでは、インポートステートメントのパッケージ名を開始点として使用して、ビルドファイルに追加する依存関係 (artifactIds) を決定します。

このトピックの情報を使用して、v1 パッケージ名を v2 artifactIds にマッピングできます。

パッケージ名と Maven artifactIds で使用される一般的な命名規則

次の表は、SDK が特定の SERVICE_ID に使用する一般的な命名規則を示しています。SERVICE_ID は、AWS のサービス の一意の識別子です。例えば、Amazon S3 サービスの SERVICE_ID は s3 であり、cognitoidentity は Amazon Cognito ID の SERVICE_ID です。

SERVICE_ID の違い

v1 内

同じサービスであっても、パッケージ名の SERVICE_ID と artifactId の SERVICE_ID が異なる場合があります。たとえば、次の表の 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 列の太字の SERVICE_ID は、v2 で使用される SERVICE_ID とは異なることを示します。