View a markdown version of this page

开始使用 - AWS 转换
先决条件安装   AWS 转换 CLI配置身份验证配置 AWS Region进行第一次转型了解转型结果创建自定义转换AWS 转换 Web 应用程序（可选）

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

开始使用

本节介绍如何设置自定义 AWS 转换并运行第一次转换。

先决条件

在安装 T AWS ransform custom 之前，请确保您具备以下条件：

支持的平台

AWS Transform custom 支持以下操作系统：

  • Linux -完全支持所有 Linux 发行版

  • macOS -完全支持 macOS 系统

  • Windows -完全支持使用 Windows 终端和 PowerShell （Windows 尚不支持这些atx ct命令）的本机 Windows

  • 适用于 Linux 的 Windows 子系统 (WSL) -在 WSL 下运行时支持

必需的软件

  • Node.js 22 或更高版本 -从以下地址下载 https://nodejs.org/en/download

  • Git -必须安装并且工作目录必须是有效的 Git 存储库才能执行转换。运行git init; git add .; git commit -m "Initial commit"以初始化工作目录中的 Git 存储库。

网络要求

需要互联网连接才能访问以下端点：

  • transform-cli.awsstatic.com

  • transform-custom.<region>.api.aws

  • *.s3.amazonaws.com

如果您在互联网限制的环境中工作，请更新防火墙规则，将这些 URL 列入允许名单。

安装   AWS 转换 CLI

推荐的安装方法是使用安装脚本。选择适用于您的操作系统的选项卡。

安装 T AWS ransform CLI

  1. 运行安装脚本：

    Linux and macOS
    curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash
    Windows (PowerShell)

    在本机 Windows 上，使用从 Windows 终端运行安装脚本 PowerShell。

    irm https://transform-cli.awsstatic.com/install.ps1 | iex

  2. 验证安装：

    atx --version

    该命令应显示已安装的 T AWS ransform CLI 版本。

配置身份验证

AWS Transform custom 需要 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"
注意

使用 $env: in 设置的环境变量仅 PowerShell 适用于当前会话。要将它们保存到会话中，请通过 “系统属性” > “环境变量” 进行设置，或使用[System.Environment]::SetEnvironmentVariable()。

AWS 凭证文件

在位于 Linux 和 macOS 或 Windows ~/.aws/credentials %USERPROFILE%\.aws\credentials 上的 AWS 凭据文件中配置凭据：

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

IAM 权限

您的 AWS 证书必须具有调用 T AWS ransform 自定义服务的权限。我们建议将AWSTransformCustomFullAccess AWS 托管策略附加到您的 IAM 用户或角色。此政策提供对 T AWS ransform 自定义的完全访问权限，包括创建向您的账户发布 CloudWatch 指标所需的服务相关角色的权限。

为了实现更精细的控制，Tran AWS sform custom 还提供以下 AWS 托管策略：

有关这些策略的更多信息，请参阅 T AWS ransform 的AWS 托管策略。有关具有资源级权限的自定义 IAM 策略，请参阅 T AWS ransform 自定义 IAM 服务授权参考指南。

注意

  • 转换定义是 AWS 带有 ARN（亚马逊资源名称）的资源。通过在 IAM 策略资源声明中指定转换 ARN，您可以使用 IAM 策略来控制对特定转换或一组转换的访问权限。标签可用于分组访问控制。

  • AWS 需要使用 IAM 身份中心才能访问 AWS 转换，但不要求使用 CLI。

配置 AWS Region

AWS Transform custom 适用于特定 AWS 区域，可使用标准 AWS CLI 优先级自动检测您的区域配置。

支持的区域：

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环境变量（最高优先级）

  2. AWS_DEFAULT_REGION 环境变量

  3. 配置文件中的选定 AWS 配置文件（通过AWS_PROFILE环境变量）

  4. 配置文件中的默认 AWS 配置文件

  5. us-east-1如果未找到配置，则默认回退到

注意

AWS 配置文件位~/.aws/config于 Linux 和 macOS 或 Windows %USERPROFILE%\.aws\config 上。

注意

如果ATX_CUSTOM_ENDPOINT已设置，则从终端节点 URL 中提取该区域并覆盖所有其他设置。

设置您的区域

选择以下方法之一来配置您的区域：

选项 1：环境变量（建议临时使用）：

Linux and macOS
export AWS_REGION=<your-region>
Windows (PowerShell)
$env:AWS_REGION="<your-region>"

选项 2： AWS CLI 配置（建议永久设置）：

aws configure set region <your-region>

选项 3： Profile-specific 配置：

Linux and macOS
aws configure set region <your-region> --profile your_profile_name
export AWS_PROFILE=your_profile_name
Windows (PowerShell)
aws configure set region <your-region> --profile your_profile_name
$env:AWS_PROFILE="your_profile_name"

选项 4：直接编辑文件：

直接编辑 AWS 配置文件（~/.aws/config在 Linux 和 macOS 上，或者%USERPROFILE%\.aws\config在 Windows 上）：

[default]
region = <your-region>

[profile your_profile_name]
region = <your-region>

验证您的区域配置

要查看 T AWS ransform custom 将使用哪个区域：

检查当前区域设置：

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（配置文件：默认）”、“AWS_REGION”、“默认”）。

重要

如果您的区域配置指向不受支持的区域，CLI 将显示一条明确的错误消息，其中包含将您的配置更新到支持的区域的说明。

进行第一次转型

最快的入门方法是使用 AWS-managed 转换。 AWS-托管转换是预先构建的、 AWS经过审查的转换，无需任何设置即可使用。

要以交互方式运行 AWS-managed 转换，请执行以下操作：

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

有关执行模式、配置选项和命令标志的详细信息，请参见Command Reference。

了解转型结果

转换完成后，T AWS ransform 自定义会提供一份描述结果的报告。如果转换未通过验证（例如成功构建 Java 应用程序），则该报告将提供进一步行动建议。

大多数转换都是分多个步骤执行的，使用 Git 提交中间转换。您可以使用标准 Git 命令查看转换所做的更改：

git status
git log
git diff <original commit-id>

创建自定义转换

当 AWS管理的转换无法满足您的需求时，您可以创建根据您的特定要求量身定制的自定义转换。

创建自定义转换

  1. 在交互模式下启动 T AWS ransform CLI：

    atx

  2. 告诉代理您要创建新的转换并描述您的需求。

  3. 提供文档和代码示例等参考材料以提高质量。

  4. 反复测试和完善转换。

  5. 将其发布到贵组织的转型注册表。

有关创建自定义转换的详细说明，请参阅工作流。

AWS 转换 Web 应用程序（可选）

T AWS ransform Web 应用程序是一个可选界面，用于监控跨多个存储库的大规模转型活动。在使用 T AWS ransform Web 应用程序之前，您需要启用用户身份才能在组织中访问 T AWS ransform。有关启用 AWS 转换的信息，请参阅设置 AWS 转换。

要使用 AWS 转换 Web 应用程序，请执行以下操作：

  1. 使用 AWS IAM 身份中心证书访问https://aws.amazon.com/transform/并登录。

  2. 在 T AWS ransform Web 应用程序中选择 “自定义/代码” 作业类型。

  3. 告诉代理您要使用的转换定义的名称。

  4. Web 应用程序提供了一个 T AWS ransform CLI 命令，可以与您的团队共享。此命令调用转换定义并将执行结果记录到 Web 应用程序。

  5. 捕获转换结果后，在控制面板中查看统计数据、节省时间的衡量标准，并询问有关工作进度的问题。

Web 应用程序专为企业级运营而设计，在这些操作中，您需要集中监控跨多个代码库的转换。

注意

AWS 访问 T AWS ransform Web 应用程序需要 IAM 身份中心。CLI 不需要 IAM 身份中心-只需要标准 AWS 证书。