As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Conceitos básicos Esta seção descreve como configurar o AWS Transform custom e executar sua primeira transformação. ## Pré-requisitos Antes de instalar o AWS Transform custom, verifique se você tem o seguinte: ### Plataformas com suporte AWS O Transform custom é compatível com os seguintes sistemas operacionais: + **Linux** - Suporte completo para todas as distribuições Linux + **macOS** - Suporte total para sistemas macOS + **Windows** - Suporte completo para Windows nativo usando o Windows Terminal e PowerShell (Os `atx ct` comandos ainda não são suportados no Windows) + **Subsistema Windows para Linux (WSL)** - Compatível quando executado em WSL ### Software necessário + **Node.js 22 ou posterior** - Faça o download em https://nodejs.org/en/download + **Git** - Deve estar instalado e o diretório de trabalho precisa ser um repositório Git válido para executar uma transformação. Execute `git init; git add .; git commit -m "Initial commit"` para inicializar um repositório Git em seu diretório de trabalho. ### Requisitos de rede É necessária uma conexão com a Internet com acesso aos seguintes endpoints: + `transform-cli.awsstatic.com` + `transform-custom..api.aws` + `*.s3.amazonaws.com` Se você estiver trabalhando em um ambiente restrito à Internet, atualize as regras de firewall para permitir esses URLs. ## Instalar o   AWS Transforme a CLI O método de instalação recomendado é usar o script de instalação. Escolha a guia do seu sistema operacional. **Para instalar a CLI do AWS Transform** 1. Execute o script de instalação: ------ #### [ Linux and macOS ] ``` curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash ``` ------ #### [ Windows (PowerShell) ] No Windows nativo, execute o script de instalação no Terminal do Windows usando PowerShell. ``` irm https://transform-cli.awsstatic.com/install.ps1 | iex ``` ------ 1. Verifique a instalação: ``` atx --version ``` O comando deve exibir a versão instalada da CLI do AWS Transform. ## Configuração da autenticação AWS O Transform custom exige AWS credenciais para se autenticar com o serviço. Configure a autenticação usando um dos métodos a seguir. ### Variáveis de ambiente Defina as seguintes variáveis de ambiente. ------ #### [ 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" ``` ------ Você também pode especificar um perfil usando a variável de `AWS_PROFILE` ambiente. ------ #### [ Linux and macOS ] ``` export AWS_PROFILE=your_profile_name ``` ------ #### [ Windows (PowerShell) ] ``` $env:AWS_PROFILE="your_profile_name" ``` ------ **nota** As variáveis de ambiente definidas com `$env:` in PowerShell se aplicam somente à sessão atual. Para mantê-los em todas as sessões, defina-os em **Propriedades do sistema** > **Variáveis de ambiente** ou use`[System.Environment]::SetEnvironmentVariable()`. ### AWS Arquivo de credenciais Configure as credenciais no arquivo de AWS credenciais, localizado no Linux e `~/.aws/credentials` no macOS, ou no Windows: `%USERPROFILE%\.aws\credentials` ``` [default] aws_access_key_id = your_access_key aws_secret_access_key = your_secret_key ``` ### Permissões do IAM Suas AWS credenciais devem ter permissões para chamar o serviço personalizado AWS Transform. Recomendamos anexar a política [`AWSTransformCustomFullAccess`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomFullAccess) AWS gerenciada ao seu usuário ou função do IAM. Essa política fornece acesso total ao AWS Transform custom, incluindo a permissão para criar a [função vinculada ao serviço](using-service-linked-roles.md#using-service-linked-roles-custom) necessária para a emissão de CloudWatch métricas para sua conta. Para um controle mais granular, o AWS Transform custom também fornece as seguintes políticas AWS gerenciadas: + [`AWSTransformCustomExecuteTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomExecuteTransformations)— Fornece acesso para executar transformações. + [`AWSTransformCustomManageTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomManageTransformations)— fornece acesso para criar, atualizar, ler e excluir recursos de transformação, bem como executar transformações. Para obter mais informações sobre essas políticas, consulte [políticas AWS gerenciadas do AWS Transform](security-iam-awsmanpol.md). Para políticas personalizadas do IAM com permissões em nível de recurso, consulte o Guia de referência de [autorização do serviço AWS Transform Custom IAM](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awstransformcustom.html). **nota** As definições de transformação são AWS recursos com ARNs (Amazon Resource Names). Você pode usar políticas do IAM para controlar o acesso a transformações específicas ou grupos de transformações especificando o ARN da transformação nas declarações de recursos da política do IAM. As tags podem ser usadas para controle de acesso agrupado. AWS O IAM Identity Center é necessário para acessar o AWS Transform, mas não é necessário usar a CLI. ## Configurar AWS Região AWS O Transform custom está disponível em AWS regiões específicas e detecta automaticamente sua configuração de região usando a precedência padrão da AWS CLI. ### Regiões aceitas AWS O Transform custom está disponível nas seguintes AWS regiões: + `us-east-1`(Leste dos EUA - Norte da Virgínia) + `eu-central-1`(Europa - Frankfurt) + `eu-west-2`(Europa - Londres) + `ca-central-1`(Canadá - Central) + `ap-northeast-1`(Ásia-Pacífico - Tóquio) + `ap-northeast-2`(Ásia-Pacífico - Seul) + `ap-southeast-2`(Ásia-Pacífico - Sydney) + `ap-south-1`(Ásia-Pacífico - Mumbai) ### Como a região é determinada A CLI verifica essas fontes em ordem prioritária para determinar qual região usar: 1. `AWS_REGION`variável de ambiente (prioridade mais alta) 1. `AWS_DEFAULT_REGION` variável de ambiente 1. Perfil selecionado no arquivo de AWS configuração (via variável de `AWS_PROFILE` ambiente) 1. Perfil padrão no AWS arquivo de configuração 1. Retorno padrão para `us-east-1` se nenhuma configuração for encontrada **nota** O arquivo de AWS configuração está localizado no Linux e `~/.aws/config` no macOS `%USERPROFILE%\.aws\config` ou no Windows. **nota** Se `ATX_CUSTOM_ENDPOINT` estiver definida, a região será extraída da URL do endpoint e substituirá todas as outras configurações. ### Definindo sua região Escolha um desses métodos para configurar sua região: **Opção 1: Variável de ambiente (recomendada para uso temporário):** ------ #### [ Linux and macOS ] ``` export AWS_REGION= ``` ------ #### [ Windows (PowerShell) ] ``` $env:AWS_REGION="" ``` ------ **Opção 2: configuração da AWS CLI (recomendada para configuração permanente):** ``` aws configure set region ``` **Opção 3: Profile-specific configuração:** ------ #### [ 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" ``` ------ **Opção 4: edição direta de arquivos:** Edite o arquivo de AWS configuração diretamente (`~/.aws/config`no Linux e no macOS `%USERPROFILE%\.aws\config` ou no Windows): ``` [default] region = [profile your_profile_name] region = ``` ### Verificando a configuração da sua região Para verificar qual região o AWS Transform custom usará: **Verifique a configuração atual da região:** ``` aws configure get region ``` **Verifique as variáveis de ambiente:** ------ #### [ 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" ``` ------ **Veja a resolução detalhada da região nos registros de depuração:** ------ #### [ Linux and macOS ] ``` tail -f ~/.aws/atx/logs/debug.log ``` ------ #### [ Windows (PowerShell) ] ``` Get-Content "$env:USERPROFILE\.aws\atx\logs\debug.log" -Wait -Tail 10 ``` ------ Exemplo de saída de log mostrando a origem da região: ``` 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" } ``` O `regionSource` campo mostra de onde a região foi derivada (por exemplo, “aws-config (profile: default)”, “AWS\_REGION”, “default”). **Importante** Se a configuração da sua região apontar para uma região sem suporte, a CLI exibirá uma mensagem de erro clara com instruções para atualizar sua configuração para uma região compatível. ## Executando sua primeira transformação A maneira mais rápida de começar é usar uma transformação AWS gerenciada. AWS-transformações gerenciadas são transformações pré-criadas e AWS aprovadas que estão prontas para uso sem qualquer configuração. **Para executar uma transformação AWS gerenciada de forma interativa:** ``` atx ``` Em seguida, peça ao agente que execute uma transformação: ``` Execute the AWS/java-aws-sdk-v1-to-v2 transformation on the codebase at ./my-java-project ``` **Para executar uma transformação de forma não interativa:** ``` atx custom def exec -n AWS/java-aws-sdk-v1-to-v2 -p ./my-java-project -c "mvn clean install" -x -t ``` Para obter informações detalhadas sobre modos de execução, opções de configuração e sinalizadores de comando, consulte[Os comandos da Referência de comandos](custom-command-reference.md). ## Entendendo os resultados da transformação Quando uma transformação é concluída, o AWS Transform custom fornece um relatório descrevendo os resultados. Se a transformação não foi validada (por exemplo, construção bem-sucedida para aplicativos Java), o relatório fornece recomendações para ações futuras. A maioria das transformações é realizada em várias etapas, usando o Git para confirmar as intermediárias. Você pode revisar as alterações feitas pela transformação usando os comandos padrão do Git: ``` git status git log git diff {{}} ``` ## Criando uma transformação personalizada Quando as transformações AWS gerenciadas não atendem às suas necessidades, você pode criar transformações personalizadas sob medida para seus requisitos específicos. **Para criar uma transformação personalizada** 1. Inicie a CLI do AWS Transform no modo interativo: ``` atx ``` 1. Diga ao agente que você deseja criar uma nova transformação e descreva seus requisitos. 1. Forneça materiais de referência, como documentação e exemplos de código, para melhorar a qualidade. 1. Teste e refine a transformação de forma iterativa. 1. Publique-o no registro de transformação da sua organização. Para obter instruções detalhadas sobre como criar transformações personalizadas, consulte[Fluxos de trabalho](custom-workflows.md). ## AWS Aplicativo Web Transform (opcional) O aplicativo web AWS Transform é uma interface opcional para monitorar campanhas de transformação em grande escala em vários repositórios. Antes de usar o aplicativo web AWS Transform, você precisa ter uma identidade de usuário habilitada para acessar o AWS Transform em sua organização. Para obter informações sobre como ativar o AWS Transform, consulte [Configurando o AWS Transform](https://docs.aws.amazon.com/transform/latest/userguide/transform-setup.html). **Para usar o aplicativo web AWS Transform:** 1. Visite https://aws.amazon.com/transform/ e faça login usando as credenciais AWS do IAM Identity Center. 1. Selecione o tipo de tarefa “Custom/code” no aplicativo web AWS Transform. 1. Diga ao agente o nome da definição de transformação que você gostaria de usar. 1. O aplicativo web fornece um comando AWS Transform CLI que pode ser compartilhado com sua equipe. Esse comando invoca a definição da transformação e registra os resultados da execução no aplicativo web. 1. Depois que os resultados da transformação forem capturados, visualize estatísticas, medições de economia de tempo e faça perguntas sobre o progresso do seu trabalho no Painel. O aplicativo web foi projetado para operações em escala empresarial, nas quais você precisa de monitoramento centralizado das transformações em várias bases de código. **nota** AWS O IAM Identity Center é necessário para acessar o aplicativo web AWS Transform. A CLI não exige o IAM Identity Center — somente AWS credenciais padrão são necessárias.