前提条件ステップ 1: 認証方法を選択し、アクセス許可を追加するステップ 2: ツールのインストールステップ 3: 依存関係のアップグレードファイルを作成する (オプション)ステップ 4: 設定および認証ステップ 5: 変換を実行する変換の一時停止またはキャンセル

Amazon Q Developer のコマンドラインで変換を実行する

Amazon Q Developer コマンドラインツールを使用してコマンドラインでコードを変換するには、次の手順を実行します。

前提条件

コマンドラインで変換を開始する前に、次の前提条件を満たす必要があります。

Java コードバージョンをアップグレードする場合、プロジェクトは Amazon Q で Java バージョンをアップグレードするための前提条件を満たしていること。
Java アプリケーションで埋め込み SQL を変換する場合、アプリケーションは Amazon Q で埋め込み SQL を変換するための前提条件を満たしていること。
コマンドライン環境に Python がインストールされていること。これは、コマンドラインツールのインストール方法です。現在サポートされている Python の最小バージョンは 3.12 です。
macOS または Linux で変換を実行していること。
アプリケーションのサイズは 2 GB 以下であること。
Amazon Q でアップグレードする特定の依存関係がある場合、依存関係のアップグレードファイルを設定済みであること。

ステップ 1: 認証方法を選択し、アクセス許可を追加する

IAM アイデンティティセンターを認証して、コマンドラインで変換を実行できます。適切なアクセス許可を持っていることを確認します。

注記

カスタマーマネージドキーは、コマンドラインで実行する変換ではサポートされていません。

アクセス許可を追加する

認証に使用する Amazon Q Developer サブスクリプションに関連付けられている IAM ID には、コマンドラインで変換を実行するアクセス許可が必要です。続行する前に、IAM ID にユーザーにコマンドラインでの変換の実行を許可するで定義されたアクセス許可があることを確認します。

Amazon Q Developer サブスクリプションを介した IAM アイデンティティセンターの認証

IAM アイデンティティセンターで認証するには、ユーザーが管理者によってワークフォースユーザーとして Amazon Q Developer Pro にサブスクライブされており、ユーザーがサブスクリプションを通じて認証するための開始 URL を指定する必要があります。ユーザーまたは管理者は、Amazon Q Developer コンソールで開始 URL を確認することができます。詳細については、「Amazon Q Developer で使用する開始 URL の表示」を参照してください。

必要なアクセス許可を追加するには、「アクセス許可を追加する」を参照してください。

ステップ 4: 設定および認証で開始 URL を指定します。

ステップ 2: ツールのインストール

変換用の Amazon Q コマンドラインツールをダウンロードして解凍します。

コマンドラインツールの以前のバージョンをダウンロードするには、「バージョン履歴」を参照してください。
ツールをインストールするには、Python で仮想環境を設定することをお勧めします。仮想環境を作成するには、ツールをインストールするディレクトリでターミナルウィンドウを開き、以下を実行します。
```
python -m venv qct-cli 
```
仮想環境を有効にするには、次の手順を実行します。
```
source qct-cli/bin/activate 
```
コマンドラインにツールをインストールするには、マシンアーキテクチャに基づいて、ツールを解凍した場所へのパスで次のコマンドを実行します。
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 をダウンロードしたバージョンに置き換えます。
ツールがインストールされていることを確認するには、以下を実行します。
```
which qct
```

ステップ 3: 依存関係のアップグレードファイルを作成する (オプション)

依存関係のアップグレードファイル、プロジェクトの依存関係を一覧表示する YAML ファイル、および変換中にアップグレードするバージョンを Amazon Q に提供できます。依存関係のアップグレードファイルを提供することで、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 アイデンティティセンターで認証し、変換の設定の詳細を指定する必要があります。

変換設定プロセスを開始するには、次のコマンドを実行します。
```
qct configure
```
サポートされている Java バージョンごとに JDK パスを入力するように求められます。Java アプリケーションのソースバージョンの JDK へのパスのみを指定する必要があり、ターゲットバージョンを指定する必要はありません。
次に、IAM アイデンティティセンターで認証するには、Amazon Q Developer Pro サブスクリプションプロファイルの開始 URL を入力するように求められます。

次に、サブスクライブした AWS リージョンを以下の形式で入力します: us-east-1。サポートされているリージョンのリストについては「サポート対象のリージョン」を参照してください。リージョンコードの一覧については、「AWS 全般のリファレンス guide」の「Regional endpoints 」を参照してください。
設定は configuration.ini ファイルに保存されます。

ステップ 5: 変換を実行する

実行する変換のタイプを選択して、必要な設定とコマンドを表示します。

注記

クライアント側のビルドでは安定したネットワーク接続が必要であるため、コード変換中にローカルマシンをオフまたは閉じないでください。

Java upgrade

変換プランの変更

Java バージョンのアップグレード中、Amazon Q は変換プランを生成し、変換を開始する前に確認できます。プランに対して次の変更をリクエストすることができます。

プランに含まれる一覧からどのライブラリを Amazon Q がアップグレードするか
- プロンプトの例:
  - <dependency1>、<dependency2>、<dependency5> のみをアップグレードする
  - <dependency1> または <dependency2> をアップグレードしない
ライブラリをアップグレードするターゲットバージョン
- プロンプトの例:
  - <version> の代わりに <dependency> をこのバージョンにアップグレードする
Amazon Q でどのステップを実行するか
- プロンプトの例:
  - ステップ 1～7 のみを完了する
  - ステップ 5～9 を実行しない
アップグレードする依存関係を追加する (新しい JDK バージョンにアップグレードする場合のみ選択可)
- プロンプトの例:
  - <dependency1> も <version2> にアップグレードする

Java コードのアップグレード

次のコマンドを実行して、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 はプランに関するフィードバックを求めません。また、変更をリクエストする機会もありません。
Maven バージョンは、変換を開始する前に検証されます。サポートされている最小バージョンがある場合は、次の出力が表示されます。
```
Running command: mvn --version at: path/to/current/directory 
Your Maven version is supported for transformations. 
```
サポートされている Maven バージョンがない場合は、更新して続行する必要があります。詳細については、「前提条件」を参照してください。
--no-interactive フラグを追加しなかった場合、Amazon Q は変換プランに関するフィードバックを提供するようプロンプトが表示されます。変更を英語の自然言語で説明できます。Amazon Q は、リクエストした変更をサポートできる場合はプランを更新します。
Amazon Q が変換を開始します。変換中にステータスの更新が出力されます。完了すると、Amazon Q は変換結果、ログ、および設定ファイルが出力されるパスを提供します。

アップグレードされたコードは、Amazon Q が作成した新しいブランチにコミットされます。Amazon Q は、qct configure の実行時に選択した内容に応じて、1 つ以上のコミットでコードをコミットします。
Java バージョンのアップグレード後に別の変換を実行している場合は、最初の変換からの変更をコミットしたのと同じブランチで 2 番目の変換を開始します。

SQL conversion

開始する前に Amazon Q Developer を使用した Java アプリケーションの埋め込み SQL の変換を読み、このタイプの変換の前提条件を理解してください。

埋め込み SQL を変換するには、まず AWS DMS スキーマ変換からスキーマメタデータファイルへのパスを含む YAML ファイルを作成する必要があります。

必要なファイル形式は次のとおりです。
```
schema_conv_metadata_path: <path-to-metadata-zip-file>
```
次のコマンドを実行して、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>
```
Amazon Q がスキーマメタデータファイルで複数のスキーマを検出した場合、変換を停止し、検出されたスキーマの一覧を提供します。SQL 変換に使用するスキーマを選択し、YAML ファイルに新しいフィールド schema: <schema-name> を追加します。
Amazon Q が変換を開始します。変換中にステータスの更新が出力されます。完了すると、Amazon Q は変換結果、ログ、および設定ファイルが出力されるパスを提供します。

アップグレードされたコードは、Amazon Q が作成した新しいブランチにコミットされます。

変換の一時停止またはキャンセル

現在の変換ジョブを一時停止またはキャンセルできます。変換ジョブは、再開するまで最大 12 時間一時停止できます。

コード変換ジョブを一時停止またはキャンセルするには、次の手順を実行します。

CLI ターミナルで、キーボードの Ctrl+C を押します。
変換を一時停止するかキャンセルするかを選択します。
- コード変換ジョブを一時停止する場合は、1 を入力します。12 時間以内にジョブを再開して、QCT コマンド `qct transform --source_folder=≤/Path/Given/Originally/To/QCT>` を使用してコード変換を続行できます。
- コード変換ジョブをキャンセルする場合は、2 を入力します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

コマンドラインでのコードの変換

トラブルシューティング