本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Amazon Q Developer 在命令列上執行轉換 完成以下步驟，以使用 Amazon Q Developer 命令列工具在命令列上轉換程式碼。 ## 先決條件 在命令列上開始轉換之前，必須符合下列先決條件： + 如果您要升級 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 上執行轉換。 + 您應用程式的大小為 2 GB 或更小。 + 如果您希望 Amazon Q 升級特定相依性，則須已設定[相依性升級檔案](#step-3-dependency-upgrade-file)。 ## 步驟 1：選擇身分驗證方法並新增許可 您可以進行 IAM Identity Center 身分驗證，以便在命令列上執行轉換。確定您具備適當的許可。 **注意** 命令列上執行的轉換不支援客戶自管金鑰。 ### 新增許可 與您用來進行身分驗證的 Amazon Q Developer 訂閱相關聯的 IAM 身分，必須具有在命令列上執行轉換的許可。繼續進行之前，請確定您的 IAM 身分具有 [允許使用者在命令列上執行轉換](id-based-policy-examples-users.md#id-based-policy-examples-allow-cli-transformations) 中定義的許可。 ### 透過 Amazon Q Developer 訂閱向 IAM Identity Center 進行身分驗證 若要向 IAM Identity Center 進行身分驗證，您的管理員必須將您[以員工使用者身分訂閱 Amazon Q Developer 專業方案](subscribe-users.md)，而且您必須提供啟動 URL 才能透過訂閱進行身分驗證。您或您的管理員可以在 Amazon Q Developer 主控台中找到啟動 URL。如需詳細資訊，請參閱 [尋找啟動 URL 以搭配 Amazon Q Developer 使用](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 Developer 專業方案訂閱設定檔的啟動 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 版本會在轉換開始之前驗證。如果您至少有最低支援版本，則會看到下列輸出： ``` 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 建立的新分支。Amazon Q 會根據您執行 `qct configure` 時所做的選擇，分成一或多次遞交程式碼。 1. 如果您在升級 Java 版本後執行另一次轉換，請在您遞交第一次轉換之變更的相同分支中啟動第二次轉換。 ------ #### [ SQL conversion ] 在開始之前，請確定您已閱讀 [使用 Amazon Q Developer 轉換 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 轉換的結構描述，然後將新欄位 `schema: {{}}` 新增至 YAML 檔案。 1. Amazon Q 開始進行轉換。它會在整個轉換過程中輸出狀態更新。完成後，Amazon Q 會提供輸出轉換結果、日誌和組態檔案的路徑。 升級後的程式碼將遞交至 Amazon Q 建立的新分支。 ------ ## 暫停或取消轉換 您可以選擇暫停或取消目前的轉換任務。您可以暫停轉換任務長達 12 小時，然後再次繼續執行。 **若要暫停或取消程式碼轉換任務** 1. 在 CLI 終端中，按下鍵盤上的 **Ctrl\+C**。 1. 選取您要暫停或取消轉換。 + 如果您要暫停程式碼轉換任務，則輸入 `1`。您可以使用下列 QCT 命令在 12 小時內繼續執行任務，以繼續程式碼轉換：``qct transform --source_folder=≤/Path/Given/Originally/To/QCT>``。 + 如果您要取消程式碼轉換任務，則輸入 `2`。