step-by-step Instruksi migrasi dengan contoh

Bagian ini menyediakan step-by-step panduan untuk memigrasikan aplikasi Anda yang saat ini menggunakan SDK for Java v1.x ke SDK for Java 2.x. Bagian pertama menyajikan ikhtisar langkah-langkah yang diikuti dengan contoh rinci migrasi.

Langkah-langkah yang dibahas di sini menjelaskan migrasi kasus penggunaan normal, di mana aplikasi memanggil Layanan AWS menggunakan klien layanan berbasis model. Jika Anda perlu memigrasikan kode yang menggunakan API tingkat yang lebih tinggi seperti S3 Transfer Manager atau CloudFrontpresigning, lihat bagian di bawah Apa yang berbeda antara AWS SDK for Java 1.x dan 2.x daftar isi.

Pendekatan yang dijelaskan di sini adalah saran. Anda dapat menggunakan teknik lain dan memanfaatkan fitur pengeditan kode IDE Anda untuk mencapai hasil yang sama.

Ikhtisar langkah-langkah

1. Mulailah dengan menambahkan SDK for Java 2.x BOM

Dengan menambahkan elemen Maven BOM (Bill of Materials) untuk SDK for Java 2.x ke file POM Anda, Anda memastikan bahwa semua ketergantungan v2 yang Anda butuhkan berasal dari versi yang sama. POM Anda dapat berisi dependensi v1 dan v2. Ini memungkinkan Anda untuk memigrasikan kode secara bertahap daripada mengubahnya sekaligus.


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

Anda dapat menemukan versi terbaru di Maven Central Repository.

2. Cari file untuk pernyataan impor kelas v1

Dengan memindai file dalam aplikasi Anda untuk Service_ids yang digunakan dalam impor v1, Anda akan menemukan Service_ids unik yang digunakan. SERVICE_ID adalah nama pendek dan unik untuk sebuah. Layanan AWS Misalnya cognitoidentity adalah SERVICE_ID untuk Identitas Amazon Cognito.

3. Tentukan dependensi Maven v2 dari pernyataan impor v1

Setelah Anda menemukan semua V1 Service_ids yang unik, Anda dapat menentukan artefak Maven yang sesuai untuk ketergantungan v2 dengan mengacu pada. Nama Package untuk pemetaan ArtifactID Maven

4. Tambahkan elemen ketergantungan v2 ke file POM

Perbarui file Maven POM dengan elemen ketergantungan ditentukan pada langkah 3.

5. Dalam file Java, secara bertahap ubah kelas v1 ke kelas v2

Saat Anda mengganti kelas v1 dengan kelas v2, buat perubahan yang diperlukan untuk mendukung API v2 seperti menggunakan pembangun alih-alih konstruktor dan menggunakan pengambil dan penyetel yang lancar.

6. Hapus dependensi v1 Maven dari impor POM dan v1 dari file

Setelah memigrasikan kode untuk menggunakan kelas v2, hapus semua impor v1 yang tersisa dari file dan semua dependensi dari file build Anda.

7. Memfaktorkan ulang kode untuk menggunakan penyempurnaan API v2

Setelah kode berhasil mengkompilasi dan lulus tes, Anda dapat memanfaatkan penyempurnaan v2 seperti menggunakan klien HTTP atau paginator yang berbeda untuk menyederhanakan kode. Ini adalah langkah opsional.

Contoh migrasi

Dalam contoh ini, kami memigrasikan aplikasi yang menggunakan SDK for Java v1 dan mengakses beberapa. Layanan AWS Kami bekerja melalui metode v1 berikut secara rinci di langkah 5. Ini adalah salah satu metode dalam kelas yang berisi delapan metode dan ada 32 kelas dalam aplikasi.

Hanya impor SDK v1 yang tercantum di bawah ini dari file Java.


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. Tambahkan v2 Maven BOM

Tambahkan Maven BOM untuk SDK for Java 2.x ke POM di samping dependensi lain di bagian tersebut. dependencyManagement Jika file POM Anda memiliki BOM untuk v1 SDK, biarkan untuk saat ini. Ini akan dihapus pada langkah selanjutnya.


<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.24.3</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

2. Cari file untuk pernyataan impor kelas v1

Cari kode aplikasi untuk kejadian unik. import com.amazonaws.services Ini membantu kami menentukan dependensi v1 yang digunakan oleh proyek. Jika aplikasi Anda memiliki file POM Maven dengan dependensi v1 terdaftar, Anda dapat menggunakan informasi ini sebagai gantinya.

Untuk contoh ini kita menggunakan perintah ripgrep(rg) untuk mencari basis kode.

Dari root basis kode Anda, jalankan ripgrep perintah berikut. Setelah ripgrep menemukan pernyataan impor, mereka disalurkan kecut,sort, dan uniq perintah untuk mengisolasi Service_ids.


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

Untuk aplikasi ini, Service_ids berikut dicatat ke konsol.


autoscaling
cloudformation
ec2
identitymanagement

Ini menunjukkan bahwa setidaknya ada satu kemunculan dari masing-masing nama paket berikut yang digunakan dalam import pernyataan. Empat tujuan kita, nama kelas individu tidak masalah. Kita hanya perlu menemukan Service_ids yang digunakan.


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

3. Tentukan dependensi Maven v2 dari pernyataan impor v1

Service_ids untuk v1 yang kami isolasi dari Langkah 2—misalnya autoscaling dan cloudformation —dapat dipetakan ke v2 SERVICE_ID yang sama untuk sebagian besar. Karena artifactID Maven v2 cocok dengan SERVICE_ID dalam banyak kasus, Anda memiliki informasi yang Anda perlukan untuk menambahkan blok ketergantungan ke file POM Anda.

Tabel berikut menunjukkan bagaimana kita dapat menentukan dependensi v2.

v1 SERVICE_ID memetakan ke... nama paket	v2 SERVICE_ID memetakan ke... nama paket	v2 Ketergantungan Maven
ec2 `com.amazonaws.services.ec2.*`	ec2 `software.amazon.awssdk.services.ec2.*`	`<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>ec2</artifactId> </dependency>`
penskalaan otomatis `com.amazonaws.services.autoscaling.*`	penskalaan otomatis `software.amazon.awssdk.services.autoscaling.*`	`<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>autoscaling</artifactId> </dependency>`
pembentukan awan `com.amazonaws.services.cloudformation.*`	pembentukan awan `software.amazon.awssdk.cloudformation.*`	`<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>cloudformation</artifactId> </dependency>`
manajemen identitas* `com.amazonaws.services.identitymanagement.*`	iam* `software.amazon.awssdk.iam.*`	`<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>iam</artifactId> </dependency>`

* The identitymanagement to iam mapping adalah pengecualian di mana SERVICE_ID berbeda antar versi. Lihat pengecualian Nama Package untuk pemetaan ArtifactID Maven untuk jika Maven atau Gradle tidak dapat menyelesaikan ketergantungan v2.

4. Tambahkan elemen ketergantungan v2 ke file POM

Pada langkah 3, kami menentukan empat blok ketergantungan yang perlu ditambahkan ke file POM. Kami tidak perlu menambahkan versi karena kami telah menentukan BOM di langkah 1. Setelah impor ditambahkan, file POM kami memiliki elemen ketergantungan berikut.


    ...
  <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. Dalam file Java, secara bertahap ubah kelas v1 ke kelas v2

Dalam metode yang kita migrasi, kita lihat

Klien layanan EC2 daricom.amazonaws.services.ec2.AmazonEC2Client.
Beberapa kelas model EC2 digunakan. Misalnya DescribeInstancesRequest danDescribeInstancesResult.


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;
}
...

Tujuan kami adalah mengganti semua impor v1 dengan impor v2. Kami melanjutkan satu kelas pada satu waktu.

sebuah. Ganti pernyataan impor atau nama kelas

Kita melihat bahwa parameter pertama untuk describeRunningInstances metode ini adalah AmazonEC2Client instance v1. Lakukan salah satu hal berikut ini:

Ganti impor untuk com.amazonaws.services.ec2.AmazonEC2Client dengan software.amazon.awssdk.services.ec2.Ec2Client dan ubah AmazonEC2Client keEc2Client.
Ubah tipe parameter menjadi Ec2Client dan biarkan IDE meminta kami untuk impor yang benar. IDE kami akan meminta kami untuk mengimpor kelas v2 karena nama klien berbeda— AmazonEC2Client danEc2Client. Pendekatan ini tidak berfungsi jika nama kelas sama di kedua versi.

b. Ganti kelas model v1 dengan setara v2

Setelah perubahan ke v2Ec2Client, jika kita menggunakan IDE, kita melihat kesalahan kompilasi dalam pernyataan berikut.


                    result = ec2.describeInstances(request);

Kesalahan kompilasi dihasilkan dari penggunaan instance v1 DescribeInstancesRequest sebagai parameter ke Ec2Client describeInstances metode v2. Untuk memperbaikinya, buat pernyataan penggantian atau impor berikut.

menggantikan	dengan
`import com.amazonaws.services.ec2.model.DescribeInstancesRequest`	`import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest`

c. Ubah konstruktor v1 menjadi pembangun v2.

Kami masih melihat kesalahan kompilasi karena tidak ada konstruktor di kelas v2. Untuk memperbaikinya, buat perubahan berikut.

perubahan kepada

perubahan	kepada
`final DescribeInstancesRequest request = new DescribeInstancesRequest() .withInstanceIds(instanceIdsCopy);`	`final DescribeInstancesRequest request = DescribeInstancesRequest.builder() .instanceIds(instanceIdsCopy) .build();`


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


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

d. Ganti objek `Result` respons v1 dengan ekuivalen v2 `Response`

Perbedaan yang konsisten antara v1 dan v2 adalah bahwa semua objek respons di v2 diakhiri dengan *Response alih-alih. *Result Ganti impor v1 ke DescribeInstancesResult impor v2,DescribeInstancesResponse.

d. Buat perubahan API

Pernyataan berikut membutuhkan beberapa perubahan.


request.setNextToken(result.getNextToken());

Dalam v2, metode setter tidak menggunakan set atau denganprefix. Metode getter yang diawali dengan get juga hilang di SDK for Java 2.x

Kelas model, seperti request instance, tidak dapat diubah di v2, jadi kita perlu membuat yang baru DescribeInstancesRequest dengan pembangun.

Dalam v2, pernyataan menjadi sebagai berikut.


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

d. Ulangi sampai metode dikompilasi dengan kelas v2

Lanjutkan dengan sisa kode. Ganti impor v1 dengan impor v2 dan perbaiki kesalahan kompilasi. Lihat Referensi API v2 dan Referensi apa yang berbeda sesuai kebutuhan.

Setelah kami memigrasikan metode tunggal ini, kami memiliki kode v2 berikut.


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;
    }
...

Karena kami memigrasikan satu metode dalam file Java dengan delapan metode, kami memiliki campuran impor v1 dan v2 saat kami mengerjakan file tersebut. Kami menambahkan enam pernyataan impor terakhir saat kami melakukan langkah-langkah.

Setelah kami memigrasikan semua kode, tidak akan ada lagi pernyataan impor v1.

6. Hapus dependensi v1 Maven dari impor POM dan v1 dari file

Setelah kami memigrasikan semua kode v1 dalam file, kami memiliki pernyataan impor SDK v2 berikut.


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;

Setelah kita memigrasikan semua file dalam aplikasi kita, kita tidak lagi membutuhkan dependensi v1 dalam file POM kita. Hapus v1 BOM dari dependencyManagement bagian, jika menggunakan, dan semua blok ketergantungan v1.

7. Memfaktorkan ulang kode untuk menggunakan penyempurnaan API v2

Untuk cuplikan yang telah kami migrasi, kami dapat menggunakan paginator v2 secara opsional dan membiarkan SDK mengelola permintaan berbasis token untuk lebih banyak data.

Kita dapat mengganti seluruh do klausa dengan yang berikut ini.


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

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Migrasi ke versi 2

Nama Package ke pemetaan ArtifactID

step-by-step Instruksi migrasi dengan contoh

Ikhtisar langkah-langkah

1. Mulailah dengan menambahkan SDK for Java 2.x BOM

2. Cari file untuk pernyataan impor kelas v1

3. Tentukan dependensi Maven v2 dari pernyataan impor v1

4. Tambahkan elemen ketergantungan v2 ke file POM

5. Dalam file Java, secara bertahap ubah kelas v1 ke kelas v2

6. Hapus dependensi v1 Maven dari impor POM dan v1 dari file

7. Memfaktorkan ulang kode untuk menggunakan penyempurnaan API v2

Contoh migrasi

1. Tambahkan v2 Maven BOM

2. Cari file untuk pernyataan impor kelas v1

3. Tentukan dependensi Maven v2 dari pernyataan impor v1

4. Tambahkan elemen ketergantungan v2 ke file POM

5. Dalam file Java, secara bertahap ubah kelas v1 ke kelas v2

sebuah. Ganti pernyataan impor atau nama kelas

b. Ganti kelas model v1 dengan setara v2

c. Ubah konstruktor v1 menjadi pembangun v2.

d. Ganti objek *Result respons v1 dengan ekuivalen v2 *Response

d. Buat perubahan API

d. Ulangi sampai metode dikompilasi dengan kelas v2

6. Hapus dependensi v1 Maven dari impor POM dan v1 dari file

7. Memfaktorkan ulang kode untuk menggunakan penyempurnaan API v2

d. Ganti objek `Result` respons v1 dengan ekuivalen v2 `Response`