Executar uma transformação na linha de comandos com o Amazon Q Developer - Amazon Q Developer
Pré-requisitosEtapa 1: selecionar o método de autenticação e adicionar permissõesEtapa 2: instalar a ferramentaEtapa 3: criar um arquivo de atualização de dependência (opcional)Etapa 4: configurar e autenticar-seEtapa 5: executar uma transformaçãoPausar ou cancelar uma transformação

Executar uma transformação na linha de comandos com o Amazon Q Developer

Conclua estas etapas para transformar seu código na linha de comandos com a ferramenta de linha de comandos do Amazon Q Developer.

Pré-requisitos

Antes de iniciar uma transformação na linha de comando, os seguintes pré-requisitos devem ser atendidos:

Etapa 1: selecionar o método de autenticação e adicionar permissões

Você pode autenticar o Centro de Identidade do IAM para executar transformações na linha de comando. Verifique se você tem as permissões necessárias.

nota

As chaves gerenciadas pelo cliente não são compatíveis com transformações realizadas na linha de comando.

Adicionar permissões

A identidade do IAM associada à assinatura do Amazon Q Developer que você está usando para se autenticar deve ter permissões para executar transformações na linha de comando. Antes de continuar, verifique se a sua identidade do IAM tem as permissões definidas em Permitir que os usuários executem transformações na linha de comandos.

Autenticar-se com o Centro de Identidade do IAM por meio de uma assinatura do Amazon Q Developer

Para se autenticar com o Centro de Identidade do IAM, você precisa ter uma assinatura do Amazon Q Developer Pro como usuário da força de trabalho pelo administrador e fornecer o URL inicial para autenticação por meio de sua assinatura. Você ou seu administrador podem encontrar o URL inicial no console do Amazon Q Developer. Para obter mais informações, consulte, Encontrar o URL inicial para uso com o Amazon Q Developer.

Para adicionar as permissões necessárias, consulte Adicionar permissões.

Você fornece o URL inicial em Etapa 4: configurar e autenticar-se.

Etapa 2: instalar a ferramenta

  1. Baixe a ferramenta de linha de comandos do Amazon Q para transformações e descompacte-a.

    Para baixar uma versão anterior da ferramenta de linha de comando, consulte Histórico de versões.

  2. Recomendamos que você configure um ambiente virtual em Python para instalar a ferramenta. Para criar um ambiente virtual, abra uma janela de terminal no diretório em que você deseja instalar a ferramenta e execute:

    python -m venv qct-cli

  3. Para ativar o ambiente virtual, execute: 

    source qct-cli/bin/activate

  4. Para instalar a ferramenta na linha de comando, execute o seguinte comando com o caminho para onde você descompactou a ferramenta, com base na arquitetura da sua 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

    Se estiver usando uma versão mais antiga da ferramenta de linha de comandos para transformações, substitua 1.2.1 pela versão que você baixou.

  5. Para verificar se a ferramenta foi instalada, execute:

    which qct

Etapa 3: criar um arquivo de atualização de dependência (opcional)

Você pode fornecer ao Amazon Q um arquivo de atualização de dependência, um arquivo YAML que lista as dependências do seu projeto e as versões para as quais atualizar durante uma transformação. Ao fornecer um arquivo de atualização de dependências, você poderá especificar dependências de terceiros e primárias que o Amazon Q talvez não saiba que precisam ser atualizadas.

As dependências primárias se referem às bibliotecas, plug-ins e estruturas que sua organização mantém e estão disponíveis somente localmente ou na rede privada da sua organização. O Amazon Q é capaz de acessar suas dependências primárias ao realizar compilações em seu ambiente local. Para obter mais informações, consulte Compilar código no ambiente local. Dependências de terceiros são dependências disponíveis publicamente ou de código aberto que não são exclusivas da sua organização.

Você pode especificar dependências primárias que deseja atualizar em um arquivo YAML, e o Amazon Q as atualiza durante a atualização do JDK (por exemplo, do Java 8 para o 17). É possível iniciar uma transformação separada (do 17 para o 17 ou do 21 para 21) após a atualização inicial do JDK para atualizar dependências de terceiros.

Após o Amazon Q realizar uma atualização mínima do JDK, você poderá iniciar uma transformação separada para atualizar todas as dependências de terceiros. Como alternativa, é possível especificar dependências de terceiros e suas versões em um arquivo YAML para atualizar somente essas dependências durante a transformação de atualização da biblioteca.

O Amazon Q solicitará que você forneça um arquivo de atualização de dependência durante a transformação. Se você quiser fornecer um, primeiro verifique se configurou o arquivo corretamente. Os seguintes campos são necessários no arquivo YAML:

  • name: o nome do arquivo de atualização de dependência.

  • description (opcional): uma descrição do arquivo de atualização da dependência e para qual transformação.

  • dependencyManagement: contém a lista de dependências e plug-ins a serem atualizados.

  • dependencies: contém o nome e a versão das bibliotecas a serem atualizadas.

  • plugins: contém os nomes e as versões dos plug-ins a serem atualizados.

  • identifier: o nome da biblioteca, plug-in ou outra dependência.

  • targetVersion: a versão da dependência para a qual atualizar.

  • versionProperty (opcional): a versão da dependência que você está definindo, conforme definida com a tag properties no arquivo pom.xml da sua aplicação.

  • originType: se a dependência é primária ou de terceiros, especificada por FIRST_PARTY ou THIRD_PARTY.

Veja a seguir um exemplo de um arquivo YAML de atualização de dependência e a configuração necessária para análise do Amazon Q:

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"

Etapa 4: configurar e autenticar-se

Antes de começar uma transformação, você deve se autenticar no Centro de Identidade do IAM e fornecer detalhes de configuração para a transformação.

  1. Para iniciar o processo de configuração da transformação, execute o seguinte comando:

    qct configure

  2. Será necessário inserir um caminho do JDK para cada versão Java compatível. Você só precisará especificar o caminho para o JDK da versão de origem da sua aplicação Java, não da versão de destino.

  3. Em seguida, para se autenticar no Centro de Identidade do IAM, você precisará inserir o URL inicial do seu perfil de assinatura do Amazon Q Developer Pro.

    Em seguida, insira a Região da AWS na qual você se inscreveu no seguinte formato: us-east-1. Para obter uma lista de regiões compatíveis, consulte Regiões do compatíveis. Para obter uma lista de códigos de região, consulte Regional endpoints no Guia Referência geral da AWS.

  4. Suas preferências de configuração são salvas em um arquivo configuration.ini.

Etapa 5: executar uma transformação

Selecione o tipo de transformação que você está executando para ver a configuração e os comandos necessários.

nota

Não desligue nem feche sua máquina local durante a transformação do código porque a compilação do lado do cliente requer uma conexão de rede estável.

Java upgrade

Modificar o plano de transformação

Durante as atualizações da versão Java, o Amazon Q gera um plano de transformação que você pode revisar antes do início da transformação. Você tem a opção de solicitar as seguintes alterações no plano:

  • Quais bibliotecas o Amazon Q atualiza, com base na lista incluída no plano

    • Exemplos de prompts:

      • Atualize somente <dependency1>, <dependency2> e <dependency5>

      • Não atualize <dependency1> ou <dependency2>

  • A versão de destino para a qual atualizar uma biblioteca

    • Exemplos de prompts:

      • Atualize <dependency> para esta versão <version>

  • Quais etapas o Amazon Q deve executar

    • Exemplos de prompts:

      • Conclua somente as etapas 1 a 7

      • Não execute as etapas 5 a 9

  • Adicionar dependências adicionais para atualizar (somente uma opção ao atualizar para uma versão mais recente do JDK)

    • Exemplos de prompts:

      • Também atualize <dependency1> para <version2>

Atualizar código Java

  1. Execute o comando a seguir para iniciar uma transformação para uma atualização do Java. Substitua <path-to-folder> pelo caminho para a pasta com o código que você está transformando e <your-target-java-version> por JAVA_17 ou JAVA_21.

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

    Opções de comando adicionais:

    • Se você estiver especificando dependências para atualizar, adicione a opção --dependency_upgrade_file com o caminho para o arquivo de atualização de dependência.

    • Se você não quiser revisar ou atualizar o plano de transformação, adicione o sinalizador --no-interactive ao comando. O Amazon Q não solicitará feedback sobre o plano e você não terá a oportunidade de solicitar alterações.

  2. Sua versão do Maven é verificada antes do início da transformação. Se você tiver pelo menos a versão mínima compatível, a seguinte saída será exibida: 

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

    Se você não tiver uma versão compatível do Maven, você deverá atualizá-lo para continuar. Para obter mais informações, consulte Pré-requisitos.

  3. Se o sinalizador --no-interactive não tiver sido adicionado, o Amazon Q solicitará que você dê feedback sobre o plano de transformação. Você pode explicar as alterações que deseja fazer em inglês natural, e o Amazon Q atualizará o plano se ele for compatível com as alterações solicitadas.

  4. O Amazon Q inicia a transformação. Ele exibirá atualizações de status durante toda a transformação. Após a conclusão, o Amazon Q fornecerá o caminho para onde os resultados da transformação, os logs e os arquivos de configuração serão enviados.

    Seu código atualizado será confirmado para a nova ramificação criada pelo Amazon Q. O Amazon Q confirmará o código em uma ou várias confirmações, dependendo da seleção que você fez ao executar qct configure.

  5. Se estiver executando outra transformação após atualizar sua versão Java, inicie a segunda transformação na mesma ramificação em que você confirmou as alterações da primeira transformação.

SQL conversion

Antes de começar, leia Converter SQL incorporado em aplicações Java com o Amazon Q Developer para entender os pré-requisitos para esse tipo de transformação.

  1. Para converter SQL incorporado, é necessário primeiro criar um arquivo YAML que contenha o caminho para o arquivo de metadados do esquema do AWS DMS Schema Conversion.

    O formato necessário do arquivo é o seguinte: 

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

  2. Execute o comando a seguir para iniciar uma transformação para uma conversão SQL. Substitua <path-to-folder> pelo caminho para a pasta com o código que você está transformando e <path-to-sql-config-file> pelo caminho para o arquivo YAML que criou na etapa 1.

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

  3. Se o Amazon Q encontrar vários esquemas em seu arquivo de metadados do esquema, ele interromperá a transformação e fornecerá uma lista dos esquemas detectados. Selecione qual esquema usar para a conversão de SQL e, em seguida, adicione um novo campo schema: <schema-name> ao arquivo YAML.

  4. O Amazon Q inicia a transformação. Ele exibirá atualizações de status durante toda a transformação. Após a conclusão, o Amazon Q fornecerá o caminho para onde os resultados da transformação, os logs e os arquivos de configuração serão enviados.

    Seu código atualizado será confirmado para a nova ramificação criada pelo Amazon Q.

Pausar ou cancelar uma transformação

Você pode optar por pausar ou cancelar seu trabalho de transformação atual. É possível pausar um trabalho de transformação por até 12 horas antes de poder retomá-lo.

Como pausar ou cancelar um trabalho de transformação de código

  1. No terminal da CLI, pressione Ctrl+C no teclado.

  2. Selecione se você deseja pausar ou cancelar sua transformação.

    • Insira 1 se quiser pausar o trabalho de transformação de código. Você pode retomar o trabalho em até 12 horas para continuar a transformação de código usando o seguinte comando QCT: `qct transform --source_folder=≤/Path/Given/Originally/To/QCT>`.

    • Insira 2 se quiser cancelar o trabalho de transformação de código.