기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Q Developer를 사용하여 명령줄에서 트랜스포메이션 실행
Amazon Q Developer 명령줄 도구를 사용하여 명령줄에서 코드를 트랜스포메이션하려면 다음 단계를 완료하세요.
## 사전 조건
명령줄에서 트랜스포메이션을 시작하기 전에 다음 사전 조건을 충족해야 합니다.
+ Java 코드 버전을 업그레이드하는 경우 프로젝트는 [Amazon Q를 사용하여 Java 버전을 업그레이드하기 위한 사전 조건](code-transformation.md#java-upgrade-prerequisites)을 충족합니다.
+ Java 애플리케이션에서 임베딩된 SQL을 변환하는 경우 애플리케이션은 [SQL with Amazon Q를 변환하기 위한 사전 조건](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 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 Pro를 직원 사용자로 구독](subscribe-users.md)해야 하며 구독을 통해 인증할 시작 URL을 제공해야 합니다. 사용자 또는 관리자는 Amazon Q Developer 콘솔에서 시작 URL을 찾을 수 있습니다. 자세한 내용은 [Amazon Q Developer에서 사용할 시작 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
```
------
**참고**
트랜스포메이션에 이전 버전의 명령줄 도구를 사용하는 경우, 다운로드한 [버전](transform-CLI-versions.md)으로 `1.2.2`을 바꿉니다.
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 Pro 구독 프로필의 시작 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을 변환하려면 먼저 [AWS DMS 스키마 변환](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html)에서 스키마 메타데이터 파일의 경로가 포함된 YAML 파일을 생성해야 합니다.
요구하는 파일 형식은 다음과 같습니다.
```
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`을 입력합니다. QCT 명령(``qct transform --source_folder=≤/Path/Given/Originally/To/QCT>``)을 사용하여 12시간 이내에 작업을 재개하여 코드 트랜스포메이션을 계속할 수 있습니다.
+ 코드 트랜스포메이션 작업을 취소하려면 `2`를 입력합니다.