Ejecución de una transformación en la línea de comandos con Amazon Q Developer - Amazon Q Developer
Requisitos previosPaso 1: elección del método de autenticación y añadido de permisosPaso 2: instalación de la herramientaPaso 3: creación de un archivo de actualización de dependencias (opcional)Paso 4: configuración y autenticaciónPaso 5: ejecución de una transformaciónPausa o cancelación de una transformación

Ejecución de una transformación en la línea de comandos con Amazon Q Developer

Realice estos pasos para transformar el código en la línea de comandos con la herramienta de línea de comandos de Amazon Q Developer.

Requisitos previos

Antes de iniciar una transformación en la línea de comandos, se deben cumplir los siguientes requisitos previos:

Paso 1: elección del método de autenticación y añadido de permisos

Puede autenticar IAM Identity Center para ejecutar transformaciones en la línea de comandos. Asegúrese de disponer de los permisos necesarios.

nota

Las claves administradas por el cliente no son compatibles con las transformaciones realizadas en la línea de comandos.

Agregar permisos

La identidad de IAM asociada a la suscripción de Amazon Q Developer que utilice para autenticarse debe contar con permisos para realizar transformaciones en la línea de comandos. Antes de continuar, asegúrese de que su identidad de IAM tiene los permisos definidos en Permiso a los usuarios para ejecutar transformaciones en la línea de comandos.

Autenticación con IAM Identity Center mediante una suscripción a Amazon Q Developer

Para autenticarse con IAM Identity Center, su administrador debe suscribirlo a Amazon Q Developer Pro como usuario de personal y debe proporcionar la URL de inicio para autenticarse mediante la suscripción. Usted o su administrador pueden encontrar la URL de inicio en la consola de Amazon Q Developer. Para obtener más información, consulte Búsqueda de la URL de inicio para el uso con Amazon Q Developer.

Para añadir los permisos necesarios, consulte Agregar permisos.

Se introduce la URL de inicio en Paso 4: configuración y autenticación.

Paso 2: instalación de la herramienta

  1. Descargue la herramienta de línea de comandos de Amazon Q para realizar transformaciones y descomprímala.

    Para descargar una versión anterior de la herramienta de línea de comandos, consulte Historial de versiones.

  2. Se recomienda configurar un entorno virtual en Python para instalar la herramienta. Para crear un entorno virtual, abra una ventana de terminal en el directorio donde desea instalar la herramienta y ejecute:

    python -m venv qct-cli

  3. Para activar el entorno virtual, ejecute: 

    source qct-cli/bin/activate

  4. Para instalar la herramienta en la línea de comandos, ejecute el siguiente comando con la ruta en la que descomprimió la herramienta, según la arquitectura de su máquina:

    Linux_aarch64
    pip install <path/to/unzipped-tool>/Linux_aarch64/amzn_qct_cli-1.2.1-py3-none-any.whl
    Linux_x86_64
    pip install <path/to/unzipped-tool>/Linux_x86_64/amzn_qct_cli-1.2.1-py3-none-any.whl
    nota

    Si está utilizando una versión anterior de la herramienta de línea de comandos para las transformaciones, reemplace 1.2.1 con la versión que descargó.

  5. Para comprobar que la herramienta se ha instalado, ejecute:

    which qct

Paso 3: creación de un archivo de actualización de dependencias (opcional)

Puede proporcionar a Amazon Q un archivo de actualización de dependencias, un archivo YAML que enumera las dependencias del proyecto y qué versiones deben actualizarse durante una transformación. Al proporcionar un archivo de actualización de dependencias, puede especificar dependencias de terceros y propias que de otro modo puede que Amazon Q no sepa que hay que actualizar.

Las dependencias propias se refieren a las bibliotecas, complementos y marcos que mantiene la organización y que solo están disponibles localmente o en la red privada de la organización. Amazon Q puede acceder a sus dependencias propias cuando realiza compilaciones en el entorno local. Para obtener más información, consulte Compilación de código en el entorno local. Las dependencias de terceros están disponibles públicamente o son dependencias de código abierto que no son exclusivas de la organización.

Puede especificar las dependencias propias que desee actualizar en un archivo YAML y Amazon Q las actualizará durante la actualización de JDK (por ejemplo, de Java 8 a 17). Puede iniciar una transformación independiente (de 17 a 17 o de 21 a 21) después de la actualización inicial de JDK para actualizar las dependencias de terceros.

Una vez que Amazon Q realice una actualización mínima de JDK, puede iniciar una transformación independiente para actualizar todas las dependencias de terceros. Como alternativa, puede especificar las dependencias de terceros y sus versiones en un archivo YAML para actualizar únicamente esas dependencias durante la transformación de la actualización de la biblioteca.

Amazon Q le pedirá que proporcione un archivo de actualización de dependencias durante la transformación. Si desea proporcionar uno, primero asegúrese de haber configurado el archivo correctamente. Los siguientes campos son obligatorios en el archivo YAML:

  • name: el nombre del archivo de actualización de dependencias.

  • description (opcional): descripción del archivo de actualización de dependencias y para qué transformación.

  • dependencyManagement: contiene la lista de dependencias y complementos que se van a actualizar.

  • dependencies: contiene el nombre y la versión de las bibliotecas que se van a actualizar.

  • plugins: contiene los nombres y las versiones de los complementos que se van a actualizar.

  • identifier: el nombre de la biblioteca, el complemento u otra dependencia.

  • targetVersion: la versión de la dependencia a la que se va a actualizar.

  • versionProperty (opcional): la versión de la dependencia que está definiendo, tal y como se establece con la etiqueta properties del archivo pom.xml de la aplicación.

  • originType: si la dependencia es propia o de un tercero, especificado por FIRST_PARTY o THIRD_PARTY.

A continuación se muestra un ejemplo de un archivo YAML de actualización de dependencias y la configuración necesaria para que Amazon Q lo analice:

name: dependency-upgrade
  
description: "Custom dependency version management for Java migration from JDK 8/11/17 to JDK 17/21"
  
  
dependencyManagement:
  
  dependencies:
  
    - identifier: "com.example:library1"
  
      targetVersion: "2.1.0"
  
      versionProperty: "library1.version"  # Optional
  
      originType: "FIRST_PARTY"   
  
    - identifier: "com.example:library2"
  
      targetVersion: "3.0.0"
  
      originType: "THIRD_PARTY"
  
  plugins:
  
    - identifier: "com.example.plugin"
  
      targetVersion: "1.2.0"
  
      versionProperty: "plugin.version"  # Optional
            
      originType: "THIRD_PARTY"

Paso 4: configuración y autenticación

Antes de comenzar una transformación, debe autenticarse en IAM Identity Center y proporcionar los detalles de configuración de la transformación.

  1. Para iniciar el proceso de configuración de la transformación, ejecute el siguiente comando:

    qct configure

  2. Se le pedirá que introduzca una ruta de JDK para cada versión de Java compatible. Solo necesita especificar la ruta al JDK de la versión de origen de la aplicación Java, no de la versión de destino.

  3. A continuación, para autenticarse en IAM Identity Center, se le pedirá que introduzca la URL de inicio del perfil de suscripción a Amazon Q Developer Pro.

    Luego, introduzca la Región de AWS donde se ha suscrito en el siguiente formato: us-east-1. Para obtener una lista de las regiones admitidas, consulte Regiones compatibles. Para obtener una lista de códigos de región, consulte Puntos de conexión regionales en la Guía de Referencia general de AWS.

  4. Sus preferencias de configuración se guardan en un archivo configuration.ini.

Paso 5: ejecución de una transformación

Elija el tipo de transformación que va a realizar para ver la configuración y los comandos necesarios.

nota

No apague ni cierre la máquina local durante la transformación del código, ya que la compilación del cliente requiere una conexión de red estable.

Java upgrade

Modificación del plan de transformación

Durante las actualizaciones de las versiones de Java, Amazon Q genera un plan de transformación que puede revisar antes de que comience la transformación. Tiene la opción de solicitar los siguientes cambios en el plan:

  • Qué bibliotecas actualiza Amazon Q, de la lista incluida en el plan

    • Ejemplos de peticiones:

      • Solo actualice <dependencia1>, <dependencia2> y <dependencia5>

      • No actualice <dependencia1> ni <dependencia2>

  • La versión de destino a la que se va a actualizar una biblioteca

    • Ejemplos de peticiones:

      • Actualice <dependencia> a esta versión en su lugar <versión>

  • Qué pasos debe realizar Amazon Q

    • Ejemplos de peticiones:

      • Realice únicamente los pasos 1 a 7

      • No ejecute los pasos 5 a 9

  • Añada dependencias adicionales para actualizar (solo es una opción cuando se actualiza a una versión más reciente de JDK)

    • Ejemplos de peticiones:

      • Actualice también <dependencia1> a <versión2>

Actualización de código Java

  1. Ejecute el siguiente comando para iniciar una transformación para una actualización de Java. Reemplace <path-to-folder> con la ruta a la carpeta con el código que está transformando y <your-target-java-version> con JAVA_17 o JAVA_21.

    qct transform --source_folder <path-to-folder>
    --target_version <your-target-java-version>

    Opciones de comandos adicionales:

    • Si está especificando las dependencias que desea actualizar, añada la opción --dependency_upgrade_file con la ruta al archivo de actualización de dependencias.

    • Si no desea revisar o actualizar el plan de transformación, añada el indicador --no-interactive a su comando. Amazon Q no le pedirá comentarios sobre el plan y no tendrá la oportunidad de solicitar cambios.

  2. La versión de Maven se verifica antes de que comience la transformación. Si tiene al menos la versión mínima compatible, obtendrá el siguiente resultado: 

    Running command: mvn --version at: path/to/current/directory 
Your Maven version is supported for transformations.

    Si no tiene una versión compatible de Maven, debe actualizarla para continuar. Para obtener más información, consulte Requisitos previos.

  3. Si no ha añadido el indicador --no-interactive, Amazon Q le pedirá que dé su opinión sobre el plan de transformación. Puede explicar los cambios que desea realizar en inglés y Amazon Q actualizará el plan si puede admitir los cambios que solicite.

  4. Amazon Q inicia la transformación. Generará actualizaciones de estado a lo largo de la transformación. Cuando finaliza, Amazon Q proporciona la ruta en la que se generan los resultados de la transformación, los registros y los archivos de configuración.

    El código actualizado se confirmará para la nueva ramificación que ha creado Amazon Q. Amazon Q confirmará el código en una o varias confirmaciones, en función de la selección que haya realizado al ejecutar qct configure.

  5. Si está ejecutando otra transformación después de actualizar su versión de Java, inicie la segunda transformación en la misma ramificación en la que confirmó los cambios de la primera transformación.

SQL conversion

Antes de empezar, asegúrese de haber leído Conversión de SQL incrustado en aplicaciones Java con Amazon Q Developer para entender los requisitos previos de este tipo de transformación para conocerlos.

  1. Para convertir SQL incrustado, primero debe crear un archivo YAML que contenga la ruta al archivo de metadatos del esquema desde la Conversión de esquema de AWS DMS.

    El archivo debe tener el siguiente formato: 

    schema_conv_metadata_path: <path-to-metadata-zip-file>

  2. Ejecute el siguiente comando para iniciar una transformación para una conversión de SQL. Reemplace <path-to-folder> con la ruta a la carpeta con el código que está transformando y <path-to-sql-config-file> con la ruta al archivo YAML que ha creado en el paso 1.

    qct transform --source_folder <path-to-folder>
    --sql_conversion_config_file <path-to-sql-config-file>

  3. Si Amazon Q encuentra varios esquemas en el archivo de metadatos del esquema, detendrá la transformación y proporcionará una lista de los esquemas detectados. Elija el esquema que desea utilizar para la conversión de SQL y, a continuación, añada un campo nuevo schema: <schema-name> al archivo YAML.

  4. Amazon Q inicia la transformación. Generará actualizaciones de estado a lo largo de la transformación. Cuando finaliza, Amazon Q proporciona la ruta en la que se generan los resultados de la transformación, los registros y los archivos de configuración.

    El código actualizado se confirmará para la nueva ramificación que ha creado Amazon Q.

Pausa o cancelación de una transformación

Puede optar por pausar o cancelar el trabajo de transformación actual. Puede pausar un trabajo de transformación durante un máximo de 12 horas antes de poder reanudarlo.

Cómo pausar o cancelar un trabajo de transformación de código

  1. En el terminal de la CLI, pulse Ctrl+C en el teclado.

  2. Seleccione si desea pausar o cancelar la transformación.

    • Introduzca 1 si desea pausar el trabajo de transformación de código. Puede reanudar el trabajo en 12 horas para continuar con la transformación del código mediante el siguiente comando de QCT: `qct transform --source_folder=≤/Path/Given/Originally/To/QCT>`.

    • Introduzca 2 si desea cancelar el trabajo de transformación de código.