Exécution d’une transformation sur la ligne de commande avec Amazon Q Developer - Amazon Q Developer
PrérequisÉtape 1 : choix de la méthode d’authentification et ajout des autorisationsÉtape 2 : installation de l’outilÉtape 3 : création d’un fichier de mise à niveau des dépendances (facultatif)Étape 4 : configuration et authentificationÉtape 5 : exécution d’une transformationMise en suspens ou annulation d’une transformation

Exécution d’une transformation sur la ligne de commande avec Amazon Q Developer

Procédez comme suit pour transformer votre code sur la ligne de commande à l’aide de l’outil de ligne de commande Amazon Q Developer.

Prérequis

Avant de commencer une transformation sur la ligne de commande, les conditions suivantes doivent être remplies :

Étape 1 : choix de la méthode d’authentification et ajout des autorisations

Vous pouvez authentifier IAM Identity Center pour exécuter des transformations sur la ligne de commande. Veillez à disposer des autorisations appropriées.

Note

Les clés gérées par le client ne sont pas prises en charge pour les transformations effectuées sur la ligne de commande.

Ajout d’autorisations

L’identité IAM associée à l’abonnement Amazon Q Developer que vous utilisez pour vous authentifier doit être autorisée à effectuer des transformations sur la ligne de commande. Avant de continuer, assurez-vous que votre identité IAM possède les autorisations définies dans Utilisateurs autorisés à exécuter des transformations sur la ligne de commande.

Authentifiez-vous auprès d’IAM Identity Center via un abonnement à Amazon Q Developer

Pour vous authentifier auprès d’IAM Identity Center, vous devez être abonné à Amazon Q Developer Pro en tant qu’utilisateur professionnel par votre administrateur et vous devez fournir l’URL de démarrage pour vous authentifier via votre abonnement. Vous ou votre administrateur pouvez trouver l’URL de démarrage dans la console Amazon Q Developer. Pour plus d’informations, consultez Recherche de l’URL de démarrage à utiliser avec Amazon Q Developer.

Pour ajouter les autorisations requises, consultez Ajout d’autorisations.

Vous fournissez l’URL de démarrage dans Étape 4 : configuration et authentification.

Étape 2 : installation de l’outil

  1. Chargez l’outil de ligne de commande Amazon Q pour les transformations et décompressez-le.

    Pour charger une version précédente de l’outil de ligne de commande, consultez Historique des versions.

  2. Nous vous conseillons de configurer un environnement virtuel en Python pour installer l’outil. Pour créer un environnement virtuel, ouvrez une fenêtre de terminal dans le répertoire où vous souhaitez installer l’outil et exécutez :

    python -m venv qct-cli

  3. Pour activer l’environnement virtuel, exécutez : 

    source qct-cli/bin/activate

  4. Pour installer l’outil sur votre ligne de commande, exécutez la commande suivante avec le chemin d’accès à l’endroit où vous avez décompressé l’outil, en fonction de l’architecture de votre machine :

    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
    Note

    Si vous utilisez une ancienne version de l’outil de ligne de commande pour les transformations, remplacez 1.2.1 par la version que vous avez chargée.

  5. Pour vérifier que l’outil a été installé, exécutez :

    which qct

Étape 3 : création d’un fichier de mise à niveau des dépendances (facultatif)

Vous pouvez fournir à Amazon Q un fichier de mise à niveau des dépendances, un fichier YAML répertoriant les dépendances de votre projet et les versions vers lesquelles effectuer la mise à niveau lors d’une transformation. En fournissant un fichier de mise à niveau des dépendances, vous pouvez spécifier les dépendances tierces et internes qu’Amazon Q ne serait peut-être pas en mesure de mettre à niveau autrement.

Les dépendances internes font référence aux bibliothèques, aux plug-ins et aux cadres gérés par votre organisation et qui ne sont disponibles que localement ou sur le réseau privé de votre organisation. Amazon Q est en mesure d’accéder à vos dépendances internes lorsqu’il réalise des builds dans votre environnement local. Pour plus d’informations, consultez Création du code dans votre environnement local. Les dépendances tierces sont des dépendances accessibles au public ou des dépendances open source qui ne sont pas propres à votre organisation.

Vous pouvez spécifier les dépendances internes que vous souhaitez mettre à niveau dans un fichier YAML et Amazon Q les met à niveau lors de la mise à niveau du JDK (par exemple, Java 8 vers 17). Vous pouvez lancer une transformation distincte (17 vers 17 ou 21 vers 21) après la mise à niveau initiale du JDK pour mettre à niveau les dépendances tierces.

Une fois qu’Amazon Q a effectué une mise à niveau minimale du JDK, vous pouvez lancer une transformation distincte pour mettre à niveau toutes les dépendances tierces. Vous pouvez également spécifier les dépendances tierces et leurs versions dans un fichier YAML pour ne mettre à niveau ces dépendances que lors de la transformation de mise à niveau de la bibliothèque.

Amazon Q vous demandera de fournir un fichier de mise à niveau des dépendances lors de la transformation. Si vous souhaitez en fournir un, vérifiez d’abord que le fichier a été configuré correctement. Les champs suivants sont obligatoires dans le fichier YAML :

  • nom : nom du fichier de mise à niveau des dépendances.

  • description (facultatif) : description du fichier de mise à niveau des dépendances et pour quelle transformation.

  • dependencyManagement : contient la liste des dépendances et des plug-ins à mettre à niveau.

  • dépendances : contient le nom et la version des bibliothèques à mettre à niveau.

  • plug-ins : contient les noms et les versions des plug-ins à mettre à niveau.

  • identifiant : nom de la bibliothèque, du plug-in ou de toute autre dépendance.

  • targetVersion : version de la dépendance vers laquelle effectuer la mise à niveau.

  • versionProperty (facultatif) : version de la dépendance que vous définissez, telle que définie avec la balise properties dans le fichier pom.xml de votre application.

  • originType : indique si la dépendance est interne ou tierce ; spécifié par FIRST_PARTY ou THIRD_PARTY.

Voici un exemple de fichier YAML de mise à niveau des dépendances et la configuration requise pour qu’Amazon Q puisse l’analyser :

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"

Étape 4 : configuration et authentification

Avant de commencer une transformation, vous devez vous authentifier auprès d’IAM Identity Center et fournir les détails de configuration de votre transformation.

  1. Pour démarrer le processus de configuration de la transformation, exécutez la commande suivante :

    qct configure

  2. Vous êtes invité à saisir le chemin du JDK pour chaque version Java prise en charge. Il vous suffit de spécifier le chemin d’accès au JDK de la version source de votre application Java, et non la version cible.

  3. Ensuite, pour vous authentifier auprès d’IAM Identity Center, vous êtes invité à saisir l’URL de démarrage de votre profil d’abonnement à Amazon Q Developer Pro.

    Ensuite, entrez la Région AWS où vous vous êtes abonné au format suivant : us-east-1. Pour obtenir une liste des régions prises en charge, consultez Régions prises en charge. Pour obtenir une liste des codes de région, consultez Points de terminaison régionaux dans le Guide Références générales AWS.

  4. Vos préférences de configuration sont enregistrées dans un fichier configuration.ini.

Étape 5 : exécution d’une transformation

Choisissez le type de transformation que vous effectuez pour voir la configuration et les commandes requises.

Note

N’éteignez pas ou ne fermez pas votre machine locale pendant la transformation du code, car la compilation côté client nécessite une connexion réseau stable.

Java upgrade

Modification du plan de transformation

Lors des mises à niveau de la version Java, Amazon Q génère un plan de transformation que vous pouvez consulter avant le début de la transformation. Vous avez la possibilité de demander les modifications suivantes au plan :

  • Quelles bibliothèques Amazon Q met à niveau, à partir de la liste incluse dans le plan

    • Exemples d’invites :

      • Effectue uniquement une mise à niveau <dépendance1>, <dépendance2> et <dépendance5>

      • N’effectue pas de mise à niveau de <dépendance1> ou <dépendance2>

  • Version cible vers laquelle mettre à niveau une bibliothèque

    • Exemples d’invites :

      • Mets à niveau <dépendance> plutôt vers cette version <version>

  • Quelles étapes Amazon Q doit effectuer

    • Exemples d’invites :

      • Effectue uniquement les étapes 1 à 7

      • N’exécute pas les étapes 5 à 9

  • Ajoute des dépendances supplémentaires à mettre à niveau (option uniquement lors de la mise à niveau vers une version plus récente du JDK)

    • Exemples d’invites :

      • Mets également à niveau la <dépendance1> vers <version2>

Mets à niveau le code Java

  1. Exécute la commande suivante pour démarrer une transformation en vue d’une mise à niveau Java. Remplace <path-to-folder> par le chemin du dossier contenant le code transformé et <your-target-java-version> par JAVA_17 ou JAVA_21.

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

    Options de commande supplémentaires :

    • Si vous spécifiez les dépendances à mettre à niveau, ajoutez l’option --dependency_upgrade_file avec le chemin d’accès à votre fichier de mise à niveau des dépendances.

    • Si vous ne souhaitez pas revoir ou mettre à jour le plan de transformation, ajoutez l’indicateur --no-interactive à votre commande. Amazon Q ne vous demandera pas de commentaires sur le plan et vous n’aurez pas la possibilité de demander des modifications.

  2. Votre version de Maven est vérifiée avant le début de la transformation. Si vous utilisez au moins la version minimale prise en charge, vous verrez la sortie suivante : 

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

    Si vous n’avez pas de version compatible de Maven, vous devez la mettre à jour pour continuer. Pour plus d’informations, consultez Prérequis.

  3. Si vous n’avez pas ajouté l’indicateur --no-interactive, Amazon Q vous invite à fournir un feedback sur le plan de transformation. Vous pouvez expliquer les modifications que vous souhaitez apporter en anglais naturel et Amazon Q mettra à jour le plan s’il prend en charge les modifications que vous demandez.

  4. Amazon Q entame la transformation. Il va afficher des mises à jour de statut tout au long de la transformation. Une fois l’opération terminée, Amazon Q fournit le chemin vers lequel les résultats de transformation, les journaux et les fichiers de configuration sont générés.

    Votre code mis à niveau sera enregistré dans la nouvelle succursale créée par Amazon Q. Amazon Q validera le code en une ou plusieurs validations, en fonction de la sélection que vous aurez effectuée lors de l’exécution de qct configure.

  5. Si vous exécutez une autre transformation après avoir mis à niveau votre version de Java, lancez la deuxième transformation dans la branche où vous avez validé les modifications depuis la première transformation.

SQL conversion

Avant de commencer, assurez-vous d’avoir lu Conversion du SQL intégré dans les applications Java avec Amazon Q Developer pour comprendre les conditions préalables à ce type de transformation.

  1. Pour convertir le SQL intégré, vous devez d’abord créer un fichier YAML contenant le chemin d’accès au fichier de métadonnées de schéma issu de votre conversion de schéma AWS DMS.

    L’URL de la requête est au format suivant : 

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

  2. Exécutez la commande suivante pour démarrer une transformation pour une conversion SQL. Remplacez <path-to-folder> par le chemin d’accès au dossier contenant le code que vous transformez et <path-to-sql-config-file> par le chemin d’accès au fichier YAML que vous avez créé à l’étape 1.

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

  3. Si Amazon Q trouve plusieurs schémas dans votre fichier de métadonnées de schéma, il arrête la transformation et fournit une liste des schémas détectés. Choisissez le schéma à utiliser pour la conversion SQL, puis ajoutez un nouveau champ schema: <schema-name> au fichier YAML.

  4. Amazon Q entame la transformation. Il va afficher des mises à jour de statut tout au long de la transformation. Une fois l’opération terminée, Amazon Q fournit le chemin vers lequel les résultats de transformation, les journaux et les fichiers de configuration sont générés.

    Votre code mis à niveau sera enregistré dans la nouvelle succursale créée par Amazon Q.

Mise en suspens ou annulation d’une transformation

Vous pouvez choisir de suspendre ou d’annuler votre tâche de transformation en cours. Vous pouvez suspendre une tâche de transformation pendant 12 heures au maximum avant de pouvoir la reprendre.

Pour suspendre ou annuler une tâche de transformation de code

  1. Dans votre terminal CLI, appuyez sur Ctrl+C sur votre clavier.

  2. Choisissez si vous souhaitez suspendre ou annuler votre transformation.

    • Saisissez 1 si vous souhaitez suspendre la tâche de transformation du code. Vous pouvez reprendre la tâche dans les 12 heures pour poursuivre la transformation du code à l’aide de la commande QCT suivante : `qct transform --source_folder=≤/Path/Given/Originally/To/QCT>`.

    • Saisissez 2 si vous souhaitez annuler la tâche de transformation du code.