使用 Amazon Q Developer 在命令列上執行轉換 - Amazon Q Developer
先決條件步驟 1：選擇身分驗證方法並新增許可步驟 2：安裝工具步驟 3：建立相依性升級檔案 (選用)步驟 4：設定和身分驗證步驟 5：執行轉換暫停或取消轉換

使用 Amazon Q Developer 在命令列上執行轉換

完成以下步驟，以使用 Amazon Q Developer 命令列工具在命令列上轉換程式碼。

先決條件

在命令列上開始轉換之前，必須符合下列先決條件：

步驟 1：選擇身分驗證方法並新增許可

您可以進行 IAM Identity Center 身分驗證，以便在命令列上執行轉換。確定您具備適當的許可。

注意

命令列上執行的轉換不支援客戶自管金鑰。

新增許可

與您用來進行身分驗證的 Amazon Q Developer 訂閱相關聯的 IAM 身分，必須具有在命令列上執行轉換的許可。繼續進行之前，請確定您的 IAM 身分具有 允許使用者在命令列上執行轉換 中定義的許可。

透過 Amazon Q Developer 訂閱向 IAM Identity Center 進行身分驗證

若要向 IAM Identity Center 進行身分驗證，您的管理員必須將您以員工使用者身分訂閱 Amazon Q Developer 專業方案，而且您必須提供啟動 URL 才能透過訂閱進行身分驗證。您或您的管理員可以在 Amazon Q Developer 主控台中找到啟動 URL。如需詳細資訊，請參閱尋找啟動 URL 以搭配 Amazon Q Developer 使用。

若要新增必要的許可，請參閱 新增許可。

您可以在 步驟 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 Developer 專業方案訂閱設定檔的啟動 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 版本會在轉換開始之前驗證。如果您至少有最低支援版本，則會看到下列輸出：

    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 建立的新分支。Amazon Q 會根據您執行 qct configure 時所做的選擇，分成一或多次遞交程式碼。

  5. 如果您在升級 Java 版本後執行另一次轉換，請在您遞交第一次轉換之變更的相同分支中啟動第二次轉換。

SQL conversion

在開始之前，請確定您已閱讀 使用 Amazon Q Developer 轉換 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 轉換的結構描述，然後將新欄位 schema: <schema-name> 新增至 YAML 檔案。

  4. Amazon Q 開始進行轉換。它會在整個轉換過程中輸出狀態更新。完成後，Amazon Q 會提供輸出轉換結果、日誌和組態檔案的路徑。

    升級後的程式碼將遞交至 Amazon Q 建立的新分支。

暫停或取消轉換

您可以選擇暫停或取消目前的轉換任務。您可以暫停轉換任務長達 12 小時，然後再次繼續執行。

若要暫停或取消程式碼轉換任務

  1. 在 CLI 終端中，按下鍵盤上的 Ctrl+C。

  2. 選取您要暫停或取消轉換。

    • 如果您要暫停程式碼轉換任務，則輸入 1。您可以使用下列 QCT 命令在 12 小時內繼續執行任務，以繼續程式碼轉換：`qct transform --source_folder=≤/Path/Given/Originally/To/QCT>`。

    • 如果您要取消程式碼轉換任務，則輸入 2。