本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 通过 Amazon Q 开发者版在命令行中运行转换作业
若要使用 Amazon Q 开发者版命令行工具在命令行中转换代码，请完成以下步骤。
## 先决条件
在命令行中启动转换作业前，必须满足以下先决条件：
+ 如果您要升级 Java 代码版本，您的项目需符合[通过 Amazon Q 升级 Java 版本的先决条件](code-transformation.md#java-upgrade-prerequisites)。
+ 如果您要转换 Java 应用中的嵌入式 SQL，您的应用需符合[通过 Amazon Q 转换嵌入式 SQL 的先决条件](transform-sql.md#sql-transform-prereqs)。
+ 您的命令行环境中已安装 Python （用于安装命令行工具），且受支持的 Python 版本不低于 3.12。
+ 您正在 macOS 或 Linux 系统上运行转换作业。
+ 应用程序大小不超过 2GB。
+ 如果您希望 Amazon Q 升级特定依赖项，需已配置[依赖项升级文件](#step-3-dependency-upgrade-file)。
## 步骤 1：选择身份验证方式并添加权限
可通过 IAM Identity Center 进行身份验证，以在命令行中运行转换作业。请确保您拥有适当的权限。
**注意**
命令行中执行的转换作业不支持客户托管密钥。
### 添加权限
用于身份验证的 Amazon Q 开发者版订阅所关联的 IAM 身份，必须具备在命令行中执行转换作业的权限。继续操作前，请确保您的 IAM 身份拥有[支持用户在命令行上运行转换](id-based-policy-examples-users.md#id-based-policy-examples-allow-cli-transformations)中定义的权限。
### 通过 Amazon Q 开发者版订阅使用 IAM Identity Center 进行身份验证
要通过 IAM Identity Center 验证身份，您需由管理员[添加为 Amazon Q 开发者版专业套餐的员工用户并完成订阅](subscribe-users.md)，且需提供订阅对应的起始 URL 以完成身份验证。您或您的管理员可在 Amazon Q 开发者版控制台中找到该起始 URL。有关更多信息，请参阅[查找用于 Amazon Q 开发者版的起始 URL](manage-account-details.md)。
要添加所需权限，请参阅[添加权限](#transform-CLI-add-permissions)。
您需在[步骤 4：配置和身份验证](#step-4-configure-auth)中提供该起始 URL。
## 步骤 2：安装工具
1. [下载 Amazon Q 命令行转换工具](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.2.zip)并解压缩。
要下载工具的旧版本，请参阅[版本历史记录](transform-CLI-versions.md)。
1. 建议在 Python 中创建虚拟环境以安装该工具。要创建虚拟环境，请在您希望安装工具的目录中打开终端窗口，然后运行以下命令：
```
python -m venv qct-cli
```
1. 要激活虚拟环境，请运行以下命令：
```
source qct-cli/bin/activate
```
1. 要在命令行中安装该工具，请根据您的计算机架构运行以下命令，其中包含该工具的解压缩路径：
------
#### [ Linux\_aarch64 ]
```
pip install /Linux_aarch64/amzn_qct_cli-1.2.2-py3-none-any.whl
```
------
#### [ Linux\_x86\_64 ]
```
pip install /Linux_x86_64/amzn_qct_cli-1.2.2-py3-none-any.whl
```
------
**注意**
如果您使用的是旧版本的命令行转换工具，请将 `1.2.2` 替换为您下载的[版本号](transform-CLI-versions.md)。
1. 要验证该工具是否已安装，请运行以下命令：
```
which qct
```
## 步骤 3：创建依赖项升级文件（可选）
您可向 Amazon Q 提供*依赖项升级文件*，这是一个 YAML 文件，用于列出项目依赖项及转换过程中需升级到的版本。通过提供该文件，您可指定 Amazon Q 可能无法自动识别的第三方依赖项和第一方依赖项，确保其得到升级。
第一方依赖项：指您的组织维护的库、插件和框架，仅在本地或组织专用网络中可用。Amazon Q 在本地环境中构建代码时，可访问这些第一方依赖项。有关更多信息，请参阅 [在本地环境中构建代码](transform-CLI.md#local-builds)。第三方依赖项：指公开可用的开源依赖项，并非您的组织专属。
您可在 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
```
1. 系统会提示您为每个受支持的 Java 版本输入 JDK 路径。您只需指定 Java 应用源版本的 JDK 路径，无需提供目标版本的路径。
1. 接下来，为通过 IAM Identity Center 验证身份，系统会提示您输入 Amazon Q 开发者版专业套餐订阅配置文件对应的起始 URL。
然后，按以下格式输入您的订阅 AWS 区域 地点：`us-east-1`。有关受支持区域的列表，请参阅[支持的区域：](regions.md)。有关区域代码的列表，请参阅《AWS 一般参考 指南》**中的[区域端点](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)。
1. 您的配置偏好会保存到 configuration.ini 文件中。
## 步骤 5：运行转换作业
根据您要执行的转换类型，查看所需配置和命令。
**注意**
代码转换过程中，请勿关闭本地计算机，因为客户端构建需要稳定的网络连接。
------
#### [ Java upgrade ]
**修改转换计划**
在 Java 版本升级过程中，Amazon Q 会生成一份转换计划，您可在转换开始前查看该计划。对于该计划，您可请求进行以下修改：
+ 指定 Amazon Q 需升级的库（从计划包含的库列表中选择）
+ 提示示例：
+ 仅升级 、 和
+ 不升级 或
+ 指定库需升级到的目标版本
+ 提示示例：
+ 将 升级到此版本（而非 版本）
+ 指定 Amazon Q 需执行的步骤
+ 提示示例：
+ 仅完成步骤 1-7
+ 不执行步骤 5-9
+ 添加需额外升级的依赖项（仅在升级到更新的 JDK 版本时可用此选项）
+ 提示示例：
+ 同时将 升级到
**升级 Java 代码**
1. 运行以下命令启动 Java 升级转换作业。将 `` 替换为待转换代码所在文件夹的路径，将 `` 替换为 `JAVA_17` 或 `JAVA_21`。
```
qct transform --source_folder {{}}
--target_version {{}}
```
额外命令选项：
+ 若需指定待升级的依赖项，请添加 `--dependency_upgrade_file` 选项，并附上您的依赖项升级文件路径。
+ 若无需查看或更新转换计划，请在命令中添加 `--no-interactive` 标志。此时 Amazon Q 不会请求您对计划提供反馈，您也无法请求修改计划。
1. 转换开始前，系统会验证您的 Maven 版本。如果您的 Maven 版本不低于最低支持版本，会看到以下输出：
```
Running command: mvn --version at: path/to/current/directory
Your Maven version is supported for transformations.
```
如果您的 Maven 版本不受支持，需先更新版本才能继续。有关更多信息，请参阅[先决条件](#CLI-transformation-prerequisites)。
1. 如果您未添加 `--no-interactive` 标志，Amazon Q 会提示您对转换计划提供反馈。您可使用自然英语说明希望进行的修改，若 Amazon Q 支持该修改，会更新转换计划。
1. Amazon Q 开始转换。并在过程中输出状态更新。转换完成后，Amazon Q 会提供转换结果、日志及配置文件的输出路径。
升级后的代码会提交到 Amazon Q 创建的新分支中。根据您运行 `qct configure` 时的选择，Amazon Q 会通过一次或多次提交完成代码提交。
1. 若要在 Java 版本升级后执行另一次转换，请在第一次转换代码提交所在的同一分支中启动第二次转换。
------
#### [ SQL conversion ]
开始前，请确保您已阅读[使用 Amazon Q 开发者版转换 Java 应用程序中的嵌入式 SQL](transform-sql.md)，了解此类转换所需满足的先决条件。
1. 要转换嵌入式 SQL，您必须先创建一个 YAML 文件，其中包含来自 [AWS DMS 架构转换](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html)的架构元数据文件路径。
以下是该文件的必填格式：
```
schema_conv_metadata_path: {{}}
```
1. 运行以下命令启动 SQL 转换作业。将 `` 替换为待转换代码所在文件夹的路径，将 `` 替换为您在步骤 1 中创建的 YAML 文件路径。
```
qct transform --source_folder {{}}
--sql_conversion_config_file {{}}
```
1. 若 Amazon Q 在您的架构元数据文件中检测到多个架构，会停止转换并列出所有检测到的架构。请选择用于 SQL 转换的架构，然后在 YAML 文件中添加新字段 `schema: {{}}`。
1. Amazon Q 开始转换。并在过程中输出状态更新。转换完成后，Amazon Q 会提供转换结果、日志及配置文件的输出路径。
升级后的代码会提交到 Amazon Q 创建的新分支中。
------
## 暂停或取消转换作业
您可以选择暂停或取消当前的转换作业。转换作业最多可暂停 12 小时，之后可恢复继续执行。
**要暂停或取消代码转换作业，请执行以下步骤：**
1. 在 CLI 终端中，按下键盘上的 **Ctrl\+C**。
1. 选择是要暂停还是取消转换。
+ 若要暂停代码转换作业，请输入 `1`。您可在 12 小时内使用以下 QCT 命令恢复作业，继续进行代码转换：``qct transform --source_folder=≤/Path/Given/Originally/To/QCT>``。
+ 若要取消代码转换作业，请输入 `2`。