本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 开始使用 本节介绍如何设置自定义 AWS 转换并运行您的第一个转换。 ## 先决条件 在安装 T AWS ransform custom 之前，请确保您具备以下条件： ### 支持的平台 AWS 自定义转换支持以下操作系统： + **Linux**-完全支持所有 Linux 发行版 + **macOS**-全面支持 macOS 系统 + **Windows**-完全支持使用 Windows 终端的本机 Windows 和 PowerShell （Windows 尚不支持这些`atx ct`命令） + 适用于 **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..api.aws` + `*.s3.amazonaws.com` 如果您在受互联网限制的环境中工作，请更新防火墙规则以将这些 URL 列入许可名单。 ## 安装   AWS 转换 CLI 推荐的安装方法是使用安装脚本。选择与您的操作系统对应的选项卡。 **安装 Trans AWS form 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 ``` ------ 1. 验证安装： ``` atx --version ``` 该命令应显示已安装的 Trans AWS form 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" ``` ------ **注意** `$env:`中设置的环境变量仅 PowerShell 适用于当前会话。要在会话中保留它们，请通过 “**系统属性**” > “**环境变量**” 进行设置，或者使用`[System.Environment]::SetEnvironmentVariable()`。 ### AWS 凭证文件 在证书文件中配置 AWS 凭据，该文件位于 Linux 和 macOS `~/.aws/credentials` 上，或者`%USERPROFILE%\.aws\credentials`在 Windows 上： ``` [default] aws_access_key_id = your_access_key aws_secret_access_key = your_secret_key ``` ### IAM 权限 您的 AWS 证书必须具有调用 Trans AWS form 自定义服务的权限。我们建议将[`AWSTransformCustomFullAccess`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomFullAccess) AWS 托管策略附加到您的 IAM 用户或角色。此政策提供对 Trans AWS form custom 的完全访问权限，包括创建向账户发布 CloudWatch 指标所需的[服务相关角色](using-service-linked-roles.md#using-service-linked-roles-custom)的权限。 为了实现更精细的控制，Trans AWS form custom 还提供了以下 AWS 托管策略： + [`AWSTransformCustomExecuteTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomExecuteTransformations)— 提供执行转换的权限。 + [`AWSTransformCustomManageTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomManageTransformations)— 提供创建、更新、读取和删除转换资源以及执行转换的权限。 有关这些策略的更多信息，请参阅 Trans [AWS form 的AWS 托管策略](security-iam-awsmanpol.md)。有关具有资源级权限的自定义 IAM 策略，请参阅[AWS 转换自定义 IAM 服务授权参考指南](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awstransformcustom.html)。 **注意** 转换定义是带有 ARN 的 AWS 资源（Amazon 资源名称）。通过在 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`环境变量（最高优先级） 1. `AWS_DEFAULT_REGION` 环境变量 1. 配置文件中选定的 AWS 配置文件（通过`AWS_PROFILE`环境变量） 1. 配置文件中的默认 AWS 配置文件 1. `us-east-1`如果未找到配置，则默认回退为 **注意** AWS 配置文件位于 Linux 和 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： Profile-specific 配置：** ------ #### [ 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 配置文件（在 Linux 和 macOS `~/.aws/config` 上，或者`%USERPROFILE%\.aws\config`在 Windows 上）： ``` [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（配置文件：默认）”、“AWS\_REGION”、“默认”）。 **重要** 如果您的区域配置指向不支持的区域，CLI 将显示一条明确的错误消息，说明如何将您的配置更新到支持的区域。 ## 运行你的第一次转型 最快的入门方法是使用 AWS托管转换。 AWS-managed 转换是预先构建的、 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 ``` 有关执行模式、配置选项和命令标志的详细信息，请参见[Command Reference](custom-command-reference.md)。 ## 了解转换结果 转换完成后，Trans AWS form custom 会提供一份描述结果的报告。如果转换未经过验证（例如，成功构建 Java 应用程序），则报告将提供进一步操作的建议。 大多数转换都是分多个步骤执行的，使用 Git 提交中间步骤。您可以使用标准 Git 命令查看转换所做的更改： ``` git status git log git diff {{}} ``` ## 创建自定义转换 当 AWS托管转换不能满足您的需求时，您可以根据您的特定要求创建自定义转换。 **创建自定义转换** 1. 在交互模式下 AWS 启动 Transform CLI： ``` atx ``` 1. 告诉代理您要创建新的转换并描述您的要求。 1. 提供参考资料，例如文档和代码样本以提高质量。 1. 反复测试和完善转换。 1. 将其发布到您组织的转型注册表。 有关创建自定义转换的详细说明，请参阅[工作流](custom-workflows.md)。 ## AWS 转换 Web 应用程序（可选） Trans AWS form Web 应用程序是一个可选界面，用于监控跨多个存储库的大规模转型活动。在使用 T AWS ransform Web 应用程序之前，您需要启用用户身份才能在组织中访问 T AWS ransform。有关启用 AWS 转换的信息，请参阅[设置 AWS 转换](https://docs.aws.amazon.com/transform/latest/userguide/transform-setup.html)。 **要使用 AWS 转换 Web 应用程序，请执行以下操作：** 1. 使用 AWS IAM 身份中心证书访问https://aws.amazon.com/transform/并登录。 1. 在 T AWS ransform Web 应用程序中选择 “自定义/代码” 作业类型。 1. 告诉代理您要使用的转换定义的名称。 1. Web 应用程序提供了可以与您的团队共享的 Transf AWS orm CLI 命令。此命令调用转换定义并将执行结果记录到 Web 应用程序。 1. 捕获转换结果后，在控制面板中查看统计数据、节省时间的衡量标准，并询问有关工作进度的问题。 Web 应用程序专为企业级操作而设计，在这些操作中，您需要集中监控多个代码库中的转换。 **注意** AWS 需要使用 IAM 身份中心才能访问 Trans AWS form Web 应用程序。CLI 不需要 IAM 身份中心，只需要标准 AWS 证书。