step-by-step Instrucciones de migración con ejemplo

En esta sección se proporciona una step-by-step guía para migrar la aplicación que actualmente utiliza la versión SDK 1.x de Java a la versión 2.x SDK de Java. La primera parte presenta una descripción general de los pasos seguidos de un ejemplo detallado de una migración.

Los pasos que se describen aquí describen la migración de un caso de uso normal, en el que la aplicación llama Servicios de AWS mediante clientes de servicio basados en modelos. Si necesita migrar un código que utilice un nivel superiorAPIs, como S3 Transfer Manager o la CloudFrontpresignación, consulte la sección situada debajo del Qué diferencia hay entre la AWS SDK for Java 1.x y la 2.x índice.

El enfoque que se describe aquí es una sugerencia. Puede utilizar otras técnicas y aprovechar sus funciones IDE de edición de código para obtener el mismo resultado.

Información general sobre los pasos

1. Comience por añadir la versión SDK 2.x para Java BOM

Al añadir el elemento Maven BOM (lista de materiales) SDK para Java 2.x a su POM archivo, se asegura de que todas las dependencias de la versión 2 que necesita son de la misma versión. POMPuede contener dependencias tanto de la versión 1 como de la versión 2. Esto te permite migrar el código de forma incremental en lugar de cambiarlo todo de una vez.

<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. Busque en los archivos las declaraciones de importación de la clase v1

Si escanea los archivos de su aplicación en busca de SERVICE _ IDs utilizados en las importaciones de la versión 1, encontrará el único SERVICE _ IDs utilizado. Un SERVICE _ID es un nombre corto y único para un Servicio de AWS. Por ejemplo, cognitoidentity es el SERVICE _ID de Amazon Cognito Identity.

3. Determine las dependencias de Maven en la versión 2 a partir de las declaraciones de importación de la versión 1

Una vez que encuentres todas las v1 SERVICE _ únicasIDs, puedes determinar el artefacto de Maven correspondiente a la dependencia v2 consultando. Package name to Maven mappings artifactId

4. Añada los elementos de dependencia de la versión 2 al archivo POM

Actualice el POM archivo Maven con los elementos de dependencia determinados en el paso 3.

5. En los archivos Java, cambie gradualmente las clases v1 a las clases v2

A medida que sustituya las clases de la versión 1 por las de la versión 2, realice los cambios necesarios para que sean compatibles con la versión 2API, como utilizar constructores en lugar de constructores y utilizar captadores y definidores fluidos.

6. Elimine las dependencias de Maven de la versión 1 y las importaciones de la versión 1 de los archivos POM

Después de migrar el código para usar las clases de la versión 2, elimina las importaciones de la versión 1 sobrantes de los archivos y todas las dependencias del archivo de compilación.

7. Refactoriza el código para usar las mejoras de la versión 2 API

Una vez que el código se haya compilado correctamente y superado las pruebas, puede aprovechar las mejoras de la versión 2, como utilizar un HTTP cliente diferente o paginadores para simplificar el código. Se trata de un paso opcional.

Ejemplo de migración

En este ejemplo, migramos una aplicación que usa la versión 1 SDK para Java y accede a varias Servicios de AWS. En el paso 5 analizaremos en detalle el siguiente método v1. Este es un método de una clase que contiene ocho métodos y hay 32 clases en la aplicación.

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. Agrega la versión 2 de Maven BOM

Agregue el Maven BOM SDK para la versión 2.x de Java POM junto con cualquier otra dependencia de la sección. dependencyManagement Si tu POM archivo tiene el valor BOM for v1 deSDK, déjalo por ahora. Se eliminará en un paso posterior.

<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. Busque en los archivos las declaraciones de importación de la clase v1

Busque en el código de la aplicación las apariciones únicas deimport com.amazonaws.services. Esto nos ayuda a determinar las dependencias de la versión 1 que utiliza el proyecto. Si su aplicación tiene un POM archivo Maven con las dependencias de la versión 1 en la lista, puede utilizar esta información en su lugar.

En este ejemplo, utilizamos el comando ripgrep(rg) para buscar en la base de código.

Desde la raíz de su base de código, ejecute el siguiente ripgrep comando. Una vez ripgrep que encuentra las sentencias de importación, se canalizan a los uniq comandos cutsort, y para aislar el SERVICE _IDs.

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

Para esta aplicación, IDs se registran los siguientes SERVICE _ en la consola.

autoscaling
cloudformation
ec2
identitymanagement

Esto indica que se utilizó al menos una vez cada uno de los siguientes nombres de paquetes en import las sentencias. Para cumplir con nuestros propósitos, los nombres de las clases individuales no importan. Solo necesitamos encontrar los SERVICE _ IDs que se utilizan.

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

3. Determine las dependencias de Maven en la versión 2 a partir de las declaraciones de importación de la versión 1

El SERVICE _ IDs para v1 que hemos aislado del paso 2 (por ejemplo, autoscaling y) se cloudformation puede asignar al mismo _ID de la versión SERVICE 2 en su mayor parte. Como el Maven de la versión 2 artifactId coincide con el SERVICE _ID en la mayoría de los casos, dispones de la información necesaria para añadir bloques de dependencias a tu archivo. POM

La siguiente tabla muestra cómo podemos determinar las dependencias de la versión 2.

<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>

* El iam mapeo identitymanagement to es una excepción en la que el SERVICE _ID difiere entre las versiones. Consulta las Package name to Maven mappings artifactId excepciones si Maven o Gradle no pueden resolver la dependencia de la versión 2.

4. Agrega los elementos de dependencia de la versión 2 al archivo POM

En el paso 3, determinamos los cuatro bloques de dependencia que se deben añadir al POM archivo. No necesitamos añadir una versión porque la especificamos BOM en el paso 1. Una vez agregadas las importaciones, nuestro POM archivo tiene los siguientes elementos de dependencia.

    ...
  <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. En los archivos Java, cambie gradualmente las clases v1 a las clases v2

En el método que estamos migrando, vemos

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

Nuestro objetivo es reemplazar todas las importaciones de la versión 1 con las importaciones de la versión 2. Procedemos una clase a la vez.

a. Reemplace la declaración de importación o el nombre de la clase

Vemos que el primer parámetro del describeRunningInstances método es una AmazonEC2Client instancia v1. Realice una de las siguientes acciones siguientes:

b. Sustituya las clases del modelo v1 por las equivalentes de la v2

Tras el cambio a la versión 2Ec2Client, si utilizamos unaIDE, veremos errores de compilación en la siguiente declaración.

                    result = ec2.describeInstances(request);

El error de compilación se debe al uso de una instancia de v1 DescribeInstancesRequest como parámetro del Ec2Client describeInstances método v2. Para solucionarlo, realiza las siguientes instrucciones de sustitución o importación.

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

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

c. Cambie los constructores v1 por constructores v2.

Seguimos viendo errores de compilación porque no hay constructores en las clases de la versión 2. Para solucionarlo, realiza el siguiente cambio.

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

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

d. Sustituya los objetos de *Result respuesta de la versión 1 por *Response equivalentes de la versión 2

Una diferencia constante entre v1 y v2 es que todos los objetos de respuesta de v2 terminan en *Response lugar de *Result. Sustituya la DescribeInstancesResult importación de la versión 1 por la importación de la versión 2,DescribeInstancesResponse.

d. Realice API cambios

La siguiente declaración necesita algunos cambios.

request.setNextToken(result.getNextToken());

En la versión 2, los métodos setter no utilizan set o withprefix. Los métodos Getter con get el prefijo de también han desaparecido en la versión 2.x de Java SDK

Las clases de modelos, como la request instancia, son inmutables en la versión 2, por lo que necesitamos crear una nueva con un constructor. DescribeInstancesRequest

En la versión 2, la sentencia pasa a ser la siguiente.

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

d. Repita el procedimiento hasta que el método se compile con las clases de la versión 2

Continúe con el resto del código. Sustituya las importaciones de la versión 1 por las de la versión 2 y corrija los errores de compilación. Consulte la APIreferencia de la versión 2 y la referencia Qué es diferente según sea necesario.

Después de migrar este único método, tenemos el siguiente código de la versión 2.

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

Como estamos migrando un único método en un archivo Java con ocho métodos, tenemos una combinación de importaciones de la versión 1 y la versión 2 a medida que avanzamos en el archivo. Añadimos las seis últimas declaraciones de importación a medida que realizábamos los pasos.

Después de migrar todo el código, no habrá más declaraciones de importación de la versión 1.

6. Elimine las dependencias de Maven de la versión 1 POM y las importaciones de la versión 1 de los archivos

Después de migrar todo el código de la versión 1 del archivo, tenemos las siguientes instrucciones de SDK importación de la versión 2.

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;

Tras migrar todos los archivos de nuestra aplicación, ya no necesitamos las dependencias de la versión 1 en nuestro POM archivo. Elimine la versión 1 BOM de la dependencyManagement sección, si la usa, y todos los bloques de dependencia de la versión 1.

7. Refactoriza el código para usar las mejoras de la versión 2 API

Para el fragmento que hemos estado migrando, podemos usar opcionalmente un paginador de la versión 2 y dejar que SDK administre las solicitudes de más datos basadas en fichas.

Podemos sustituir toda la cláusula por lo siguiente. 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);
                                    }
                                }));

Package name to Maven mappings artifactId

Cuando migres tu proyecto de Maven o Gradle de la versión 1 SDK para Java a la v2, tendrás que averiguar qué dependencias añadir al archivo de compilación. El enfoque descrito en el step-by-step Instrucciones de migración con ejemplo (paso 3) utiliza los nombres de los paquetes de las instrucciones de importación como punto de partida para determinar las dependencias que se van a añadir al archivo de compilación. artifactIds

Puedes usar la información de este tema para asignar los nombres de los paquetes de la versión 1 a la versión artifactIds 2.

Convención de nomenclatura común utilizada en los nombres de paquetes y en Maven artifactIds

La siguiente tabla muestra la convención de nomenclatura común que se SDKs utiliza para un SERVICE _ID determinado. Un SERVICE _ID es un identificador único para un. Servicio de AWS Por ejemplo, el SERVICE _ID del servicio Amazon S3 es s3 y cognitoidentity es el SERVICE _ID de Amazon Cognito Identity.

SERVICEDiferencias de _ID

Dentro de la v1

En algunos casos, el SERVICE _ID difiere entre el nombre del paquete y el artifactId del mismo servicio. Por ejemplo, la fila CloudWatch Métricas de la siguiente tabla muestra que metrics es el SERVICE _ID del nombre del paquete, pero cloudwatchmetrics artifactId es SERVICE el _ID.

Dentro de la versión 2

No hay diferencias en el SERVICE _ID utilizado en los nombres de los paquetes yartifactIds.

Entre v1 y v2

Para la mayoría de los servicios, el SERVICE _ID de la versión 2 es el mismo que el SERVICE _ID de la versión 1 en los nombres de los paquetes y. artifactIds Un ejemplo de esto es el cognitoedentity SERVICE _ID, tal como se muestra en la tabla anterior. Sin embargo, algunos SERVICE _ IDs difieren entre sí, SDKs como se muestra en la siguiente tabla.

Un SERVICE_ID en negrita en cualquiera de las columnas de la versión 1 indica que es diferente del SERVICE _ID utilizado en la versión 2.