通过 Amazon Q 开发者版在命令行中运行转换作业 - Amazon Q 开发者版
先决条件步骤 1：选择身份验证方式并添加权限步骤 2：安装工具步骤 3：创建依赖项升级文件（可选）步骤 4：配置和身份验证步骤 5：运行转换作业暂停或取消转换作业

通过 Amazon Q 开发者版在命令行中运行转换作业

若要使用 Amazon Q 开发者版命令行工具在命令行中转换代码，请完成以下步骤。

先决条件

在命令行中启动转换作业前，必须满足以下先决条件：

步骤 1：选择身份验证方式并添加权限

可通过 IAM Identity Center 进行身份验证，以在命令行中运行转换作业。请确保您拥有适当的权限。

注意

命令行中执行的转换作业不支持客户托管密钥。

添加权限

用于身份验证的 Amazon Q 开发者版订阅所关联的 IAM 身份，必须具备在命令行中执行转换作业的权限。继续操作前，请确保您的 IAM 身份拥有支持用户在命令行上运行转换中定义的权限。

通过 Amazon Q 开发者版订阅使用 IAM Identity Center 进行身份验证

要通过 IAM Identity Center 验证身份，您需由管理员添加为 Amazon Q 开发者版专业套餐的员工用户并完成订阅，且需提供订阅对应的起始 URL 以完成身份验证。您或您的管理员可在 Amazon Q 开发者版控制台中找到该起始 URL。有关更多信息，请参阅查找用于 Amazon Q 开发者版的起始 URL。

要添加所需权限，请参阅添加权限。

您需在步骤 4：配置和身份验证中提供该起始 URL。

步骤 2：安装工具

  1. 下载 Amazon Q 命令行转换工具并解压缩。

    要下载工具的旧版本，请参阅版本历史记录。

  2. 建议在 Python 中创建虚拟环境以安装该工具。要创建虚拟环境，请在您希望安装工具的目录中打开终端窗口，然后运行以下命令：

    python -m venv qct-cli

  3. 要激活虚拟环境，请运行以下命令：

    source qct-cli/bin/activate

  4. 要在命令行中安装该工具，请根据您的计算机架构运行以下命令，其中包含该工具的解压缩路径：

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

    如果您使用的是旧版本的命令行转换工具，请将 1.2.1 替换为您下载的版本号。

  5. 要验证该工具是否已安装，请运行以下命令：

    which qct

步骤 3：创建依赖项升级文件（可选）

您可向 Amazon Q 提供依赖项升级文件，这是一个 YAML 文件，用于列出项目依赖项及转换过程中需升级到的版本。通过提供该文件，您可指定 Amazon Q 可能无法自动识别的第三方依赖项和第一方依赖项，确保其得到升级。

第一方依赖项：指您的组织维护的库、插件和框架，仅在本地或组织专用网络中可用。Amazon Q 在本地环境中构建代码时，可访问这些第一方依赖项。有关更多信息，请参阅在本地环境中构建代码。第三方依赖项：指公开可用的开源依赖项，并非您的组织专属。

您可在 YAML 文件中指定需升级的第一方依赖项，Amazon Q 会在 JDK 升级（例如从 Java 8 到 17）过程中对其进行升级。初始 JDK 升级完成后，您可启动单独的转换作业（如从 17 到 17、从 21 到 21）来升级第三方依赖项。

Amazon Q 完成最低版本 JDK 升级后，您可启动单独的转换作业以升级所有第三方依赖项；或者，也可在 YAML 文件中指定第三方依赖项及其版本，仅在库升级转换过程中升级这些指定的依赖项。

转换过程中，Amazon Q 会提示您提供依赖项升级文件。如需提供，请先确保文件配置正确。YAML 文件中必须包含以下字段：

  • name：依赖项升级文件的名称。

  • description（可选）：依赖项升级文件的描述，及该文件对应的转换场景。

  • dependencyManagement：包含需升级的依赖项和插件列表。

  • dependencies：包含需升级的库的名称和版本。

  • plugins：包含需升级的插件的名称和版本。

  • identifier：库、插件或其他依赖项的名称。

  • targetVersion：依赖项需升级到的版本。

  • versionProperty（可选）：依赖项的版本（在应用的 pom.xml 文件中通过 properties 标签定义）。

  • originType：依赖项类型，需指定为 FIRST_PARTY 或 THIRD_PARTY。

以下是依赖项升级 YAML 文件及 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"

步骤 4：配置和身份验证

在启动转换作业前，您必须通过 IAM Identity Center 完成身份验证，并提供转换所需的配置详情。

  1. 要启动转换配置流程，请运行以下命令：

    qct configure

  2. 系统会提示您为每个受支持的 Java 版本输入 JDK 路径。您只需指定 Java 应用源版本的 JDK 路径，无需提供目标版本的路径。

  3. 接下来，为通过 IAM Identity Center 验证身份，系统会提示您输入 Amazon Q 开发者版专业套餐订阅配置文件对应的起始 URL。

    然后，按以下格式输入您订阅时所在的 AWS 区域：us-east-1。有关受支持区域的列表，请参阅支持的区域。有关区域代码的列表，请参阅《AWS 一般参考 指南》中的区域端点。

  4. 您的配置偏好会保存到 configuration.ini 文件中。

步骤 5：运行转换作业

根据您要执行的转换类型，查看所需配置和命令。

注意

代码转换过程中，请勿关闭本地计算机，因为客户端构建需要稳定的网络连接。

Java upgrade

修改转换计划

在 Java 版本升级过程中，Amazon Q 会生成一份转换计划，您可在转换开始前查看该计划。对于该计划，您可请求进行以下修改：

  • 指定 Amazon Q 需升级的库（从计划包含的库列表中选择）

    • 提示示例：

      • 仅升级 <dependency1>、<dependency2> 和 <dependency5>

      • 不升级 <dependency1> 或 <dependency2>

  • 指定库需升级到的目标版本

    • 提示示例：

      • 将 <dependency> 升级到此版本（而非 <version> 版本）

  • 指定 Amazon Q 需执行的步骤

    • 提示示例：

      • 仅完成步骤 1-7

      • 不执行步骤 5-9

  • 添加需额外升级的依赖项（仅在升级到更新的 JDK 版本时可用此选项）

    • 提示示例：

      • 同时将 <dependency1> 升级到 <version2>

升级 Java 代码

  1. 运行以下命令启动 Java 升级转换作业。将 <path-to-folder> 替换为待转换代码所在文件夹的路径，将 <your-target-java-version> 替换为 JAVA_17 或 JAVA_21。

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

    额外命令选项：

    • 若需指定待升级的依赖项，请添加 --dependency_upgrade_file 选项，并附上您的依赖项升级文件路径。

    • 若无需查看或更新转换计划，请在命令中添加 --no-interactive 标志。此时 Amazon Q 不会请求您对计划提供反馈，您也无法请求修改计划。

  2. 转换开始前，系统会验证您的 Maven 版本。如果您的 Maven 版本不低于最低支持版本，会看到以下输出：

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

    如果您的 Maven 版本不受支持，需先更新版本才能继续。有关更多信息，请参阅先决条件。

  3. 如果您未添加 --no-interactive 标志，Amazon Q 会提示您对转换计划提供反馈。您可使用自然英语说明希望进行的修改，若 Amazon Q 支持该修改，会更新转换计划。

  4. 随后 Amazon Q 开始执行转换作业，并在过程中输出状态更新。转换完成后，Amazon Q 会提供转换结果、日志及配置文件的输出路径。

    升级后的代码会提交到 Amazon Q 创建的新分支中。根据您运行 qct configure 时的选择，Amazon Q 会通过一次或多次提交完成代码提交。

  5. 若要在 Java 版本升级后执行另一次转换，请在第一次转换代码提交所在的同一分支中启动第二次转换。

SQL conversion

开始前，请确保您已阅读使用 Amazon Q 开发者版转换 Java 应用程序中的嵌入式 SQL，了解此类转换所需满足的先决条件。

  1. 要转换嵌入式 SQL，您必须先创建一个 YAML 文件，其中包含来自 AWS DMS 架构转换的架构元数据文件路径。

    以下是该文件的必填格式：

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

  2. 运行以下命令启动 SQL 转换作业。将 <path-to-folder> 替换为待转换代码所在文件夹的路径，将 <path-to-sql-config-file> 替换为您在步骤 1 中创建的 YAML 文件路径。

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

  3. 若 Amazon Q 在您的架构元数据文件中检测到多个架构，会停止转换并列出所有检测到的架构。请选择用于 SQL 转换的架构，然后在 YAML 文件中添加新字段 schema: <schema-name>。

  4. 随后 Amazon Q 开始执行转换作业，并在过程中输出状态更新。转换完成后，Amazon Q 会提供转换结果、日志及配置文件的输出路径。

    升级后的代码会提交到 Amazon Q 创建的新分支中。

暂停或取消转换作业

您可以选择暂停或取消当前的转换作业。转换作业最多可暂停 12 小时，之后可恢复继续执行。

要暂停或取消代码转换作业，请执行以下步骤：

  1. 在 CLI 终端中，按下键盘上的 Ctrl+C。

  2. 选择是要暂停还是取消转换。

    • 若要暂停代码转换作业，请输入 1。您可在 12 小时内使用以下 QCT 命令恢复作业，继续进行代码转换：`qct transform --source_folder=≤/Path/Given/Originally/To/QCT>`。

    • 若要取消代码转换作业，请输入 2。