本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開始使用 本節說明如何設定 AWS 轉換自訂並執行您的第一個轉換。 ## 先決條件 在安裝 AWS 轉換自訂之前，請確定您有下列項目： ### 支援的平台 AWS 轉換自訂支援下列作業系統： + **Linux** - 完整支援所有 Linux 發行版本 + **macOS** - macOS 系統的完整支援 + **Windows** - 使用 Windows Terminal 和 PowerShell 完整支援原生 Windows (Windows 尚未支援這些`atx ct`命令） + **適用於 Linux 的 Windows 子系統 (WSL)** - 在 WSL 下執行時支援 ### 必要軟體 + **Node.js 22 或更新版本** - 從 https：//https://nodejs.org/en/download 下載 + **Git** - 必須安裝，且工作目錄必須是有效的 Git 儲存庫才能執行轉換。執行 `git init; git add .; git commit -m "Initial commit"` 以初始化您工作目錄中的 Git 儲存庫。 ### 網路要求 需要可存取下列端點的網際網路連線： + `transform-cli.awsstatic.com` + `transform-custom..api.aws` + `*.s3.amazonaws.com` 如果您在限制網際網路的環境中工作，請更新防火牆規則以允許列出這些 URLs。 ## 安裝 AWS 轉換 CLI 建議的安裝方法使用 安裝指令碼。選擇作業系統的索引標籤。 **安裝 AWS 轉換 CLI** 1. 執行安裝指令碼： ------ #### [ Linux and macOS ] ``` curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash ``` ------ #### [ Windows (PowerShell) ] 在原生 Windows 上，使用 PowerShell 從 Windows 終端機執行安裝指令碼。 ``` irm https://transform-cli.awsstatic.com/install.ps1 | iex ``` ------ 1. 驗證安裝： ``` atx --version ``` 命令應會顯示 AWS Transform CLI 的安裝版本。 ## 設定身分驗證 AWS 轉換自訂需要 AWS 登入資料，才能使用 服務進行驗證。使用下列其中一種方法設定身分驗證。 ### 環境變數 設定下列環境變數。 ------ #### [ Linux and macOS ] ``` export AWS_ACCESS_KEY_ID=your_access_key export AWS_SECRET_ACCESS_KEY=your_secret_key export AWS_SESSION_TOKEN=your_session_token ``` ------ #### [ Windows (PowerShell) ] ``` $env:AWS_ACCESS_KEY_ID="your_access_key" $env:AWS_SECRET_ACCESS_KEY="your_secret_key" $env:AWS_SESSION_TOKEN="your_session_token" ``` ------ 您也可以使用 `AWS_PROFILE`環境變數指定設定檔。 ------ #### [ Linux and macOS ] ``` export AWS_PROFILE=your_profile_name ``` ------ #### [ Windows (PowerShell) ] ``` $env:AWS_PROFILE="your_profile_name" ``` ------ **注意** 在 PowerShell `$env:`中使用 設定的環境變數僅適用於目前的工作階段。若要跨工作階段保留它們，請透過**系統屬性** > **環境變數**進行設定，或使用 `[System.Environment]::SetEnvironmentVariable()`。 ### AWS 登入資料檔案 在登入資料檔案中設定 AWS 登入資料，位於 Linux 和 macOS `~/.aws/credentials` 上的 ，或位於 Windows `%USERPROFILE%\.aws\credentials`上的 ： ``` [default] aws_access_key_id = your_access_key aws_secret_access_key = your_secret_key ``` ### IAM 許可 您的 AWS 登入資料必須具有呼叫 AWS 轉換自訂服務的許可。建議您將 [`AWSTransformCustomFullAccess`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomFullAccess) AWS 受管政策連接至 IAM 使用者或角色。此政策提供 AWS 轉換自訂的完整存取權，包括建立 CloudWatch 指標傳送至您的帳戶所需的[服務連結角色](using-service-linked-roles.md#using-service-linked-roles-custom)的許可。 如需更精細的控制， AWS Transform 自訂也提供下列 AWS 受管政策： + [`AWSTransformCustomExecuteTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomExecuteTransformations) – 提供執行轉換的存取權。 + [`AWSTransformCustomManageTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomManageTransformations) – 提供建立、更新、讀取和刪除轉換資源的存取權，以及執行轉換。 如需這些政策的詳細資訊，請參閱 [AWSAWS Transform 的 受管政策](security-iam-awsmanpol.md)。如需具有資源層級許可的自訂 IAM 政策，請參閱 [AWS 轉換自訂 IAM 服務授權參考指南](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awstransformcustom.html)。 **注意** 轉換定義是具有 ARNs(Amazon Resource Name) AWS 的資源。您可以使用 IAM 政策，在 IAM 政策資源陳述式中指定轉換 ARN，以控制對特定轉換或轉換群組的存取。標籤可用於分組存取控制。 AWS 存取 AWS 轉換需要 IAM Identity Center，但使用 CLI 不需要。 ## 設定 AWS 區域 AWS 轉換自訂可在特定 AWS 區域使用，並使用標準 CLI AWS 優先順序自動偵測您的區域組態。 ### 支援的區域 AWS 轉換自訂可在下列 AWS 區域使用： + `us-east-1` （美國東部 - 維吉尼亞北部） + `eu-central-1` （歐洲 - 法蘭克福） + `eu-west-2` （歐洲 - 倫敦） + `ca-central-1` （加拿大 - 中部） + `ap-northeast-1` （亞太區域 - 東京） + `ap-northeast-2` （亞太區域 - 首爾） + `ap-southeast-2` （亞太區域 - 雪梨） + `ap-south-1` （亞太區域 - 孟買） ### 區域如何決定 CLI 會依優先順序檢查這些來源，以決定要使用的區域： 1. `AWS_REGION` 環境變數 （最高優先順序） 1. `AWS_DEFAULT_REGION` 環境變數 1. 組態檔案中選取的設定檔 AWS （透過`AWS_PROFILE`環境變數） 1. AWS 組態檔案中的預設設定檔 1. `us-east-1` 如果找不到組態，預設回復至 **注意** 組態檔案位於 Linux AWS 和 macOS `~/.aws/config` 上的 ，或 Windows `%USERPROFILE%\.aws\config`上的 。 **注意** 如果`ATX_CUSTOM_ENDPOINT`已設定 ，則會從端點 URL 擷取區域，並覆寫所有其他設定。 ### 設定您的區域 選擇下列其中一種方法來設定您的區域： **選項 1：環境變數 （建議暫時使用）：** ------ #### [ Linux and macOS ] ``` export AWS_REGION= ``` ------ #### [ Windows (PowerShell) ] ``` $env:AWS_REGION="" ``` ------ **選項 2： AWS CLI 組態 （建議永久設定）：** ``` aws configure set region ``` **選項 3：設定檔特定的組態：** ------ #### [ Linux and macOS ] ``` aws configure set region --profile your_profile_name export AWS_PROFILE=your_profile_name ``` ------ #### [ Windows (PowerShell) ] ``` aws configure set region --profile your_profile_name $env:AWS_PROFILE="your_profile_name" ``` ------ **選項 4：直接檔案編輯：** 直接編輯組態檔案 AWS (`~/.aws/config`在 Linux 和 macOS 或 Windows `%USERPROFILE%\.aws\config`上）： ``` [default] region = [profile your_profile_name] region = ``` ### 驗證您的區域組態 若要檢查 AWS 轉換自訂將使用的區域： **檢查目前的區域設定：** ``` aws configure get region ``` **檢查環境變數：** ------ #### [ Linux and macOS ] ``` echo "AWS_REGION: $AWS_REGION" echo "AWS_DEFAULT_REGION: $AWS_DEFAULT_REGION" echo "AWS_PROFILE: $AWS_PROFILE" ``` ------ #### [ Windows (PowerShell) ] ``` echo "AWS_REGION: $env:AWS_REGION" echo "AWS_DEFAULT_REGION: $env:AWS_DEFAULT_REGION" echo "AWS_PROFILE: $env:AWS_PROFILE" ``` ------ **在偵錯日誌中檢視詳細的區域解析：** ------ #### [ Linux and macOS ] ``` tail -f ~/.aws/atx/logs/debug.log ``` ------ #### [ Windows (PowerShell) ] ``` Get-Content "$env:USERPROFILE\.aws\atx\logs\debug.log" -Wait -Tail 10 ``` ------ 顯示區域來源的日誌輸出範例： ``` 2026-01-07 22:34:28 [DEBUG]: Initializing FrontendServiceClient with config: { "endpoint": "https://transform-custom.us-east-1.api.aws", "region": "us-east-1", "regionSource": "AWS_REGION" } ``` `regionSource` 欄位顯示區域衍生自何處 （例如 "aws-config （設定檔： default)"、"AWS\_REGION"、"default")。 **重要** 如果您的區域組態指向不支援的區域，CLI 會顯示明確的錯誤訊息，其中包含將組態更新為支援區域的指示。 ## 執行您的第一個轉換 開始使用的最快方法是使用 AWS受管轉換。 AWS受管轉換是預先建置、經過 AWS審核的轉換，無需任何設定即可使用。 **若要以互動方式執行受 AWS管轉換：** ``` atx ``` 然後要求代理程式執行轉換： ``` Execute the AWS/java-aws-sdk-v1-to-v2 transformation on the codebase at ./my-java-project ``` **若要以非互動方式執行轉換：** ``` atx custom def exec -n AWS/java-aws-sdk-v1-to-v2 -p ./my-java-project -c "mvn clean install" -x -t ``` 如需執行模式、組態選項和命令旗標的詳細資訊，請參閱 [命令參考](custom-command-reference.md)。 ## 了解轉換結果 當轉換完成時， AWS Transform 自訂會提供描述結果的報告。如果轉換未經過驗證 （例如，Java 應用程式的成功建置），則報告會提供進一步動作的建議。 大多數轉換都是以多個步驟執行，使用 Git 遞交中繼轉換。您可以使用標準 Git 命令檢閱轉換所做的變更： ``` git status git log git diff {{}} ``` ## 建立自訂轉換 當 AWS受管轉換不符合您的需求時，您可以根據特定需求建立自訂轉換。 **建立自訂轉換** 1. 在互動式模式下啟動 AWS 轉換 CLI： ``` atx ``` 1. 告訴客服人員您要建立新的轉換並描述您的需求。 1. 提供參考資料，例如文件和程式碼範例，以改善品質。 1. 反覆測試和精簡轉換。 1. 將其發佈到組織的轉換登錄檔。 如需建立自訂轉換的詳細說明，請參閱 [工作流程](custom-workflows.md)。 ## AWS 轉換 Web 應用程式 （選用） AWS 轉換 Web 應用程式是選擇性的界面，用於監控跨多個儲存庫的大規模轉換行銷活動。在使用 AWS 轉換 Web 應用程式之前，您需要啟用使用者身分，才能存取組織中的 AWS 轉換。如需啟用 AWS 轉換的資訊，請參閱[設定 AWS 轉換](https://docs.aws.amazon.com/transform/latest/userguide/transform-setup.html)。 **若要使用 AWS 轉換 Web 應用程式：** 1. 請造訪 https://aws.amazon.com/transform/：// 並使用 AWS IAM Identity Center 登入資料登入。 1. 在 AWS 轉換 Web 應用程式中選取「自訂/程式碼」任務類型。 1. 告訴客服人員您要使用的轉換定義名稱。 1. Web 應用程式提供 AWS Transform CLI 命令，可與您的團隊共用。此命令會叫用轉換定義，並將執行結果記錄到 Web 應用程式。 1. 擷取轉換結果後，請在儀表板中檢視統計資料、節省時間測量，並詢問任務進度的問題。 Web 應用程式專為企業規模操作而設計，您需要集中監控跨多個程式碼庫的轉換。 **注意** AWS 存取 AWS Transform Web 應用程式需要 IAM Identity Center。CLI 不需要 IAM Identity Center - 只需要標準 AWS 登入資料。