View a markdown version of this page

Nozioni di base - AWS Trasformazione
PrerequisitiInstallazione di AWS Trasforma la CLIConfigurazione dell'autenticazioneConfigurazione AWS RegionEsecuzione della prima trasformazioneComprensione dei risultati della trasformazioneCreazione di una trasformazione personalizzataAWS Trasforma l'applicazione Web (opzionale)

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Nozioni di base

Questa sezione descrive come configurare AWS Transform personalizzato ed eseguire la prima trasformazione.

Prerequisiti

Prima di installare AWS Transform custom, assicurati di avere quanto segue:

Piattaforme supportate

AWS Transform custom supporta i seguenti sistemi operativi:

  • Linux: supporto completo per tutte le distribuzioni Linux

  • macOS - Supporto completo per i sistemi macOS

  • Windows: supporto completo per Windows nativo tramite Windows Terminal e PowerShell (i atx ct comandi non sono ancora supportati su Windows)

  • Windows Subsystem for Linux (WSL) - Supportato se eseguito con WSL

Software richiesto

  • Node.js 22 o versione successiva: scarica da https://nodejs.org/en/download

  • Git: deve essere installato e la directory di lavoro deve essere un repository Git valido per eseguire una trasformazione. Esegui git init; git add .; git commit -m "Initial commit" per inizializzare un repository Git nella tua directory di lavoro.

Requisiti di rete

È richiesta una connessione Internet con accesso ai seguenti endpoint:

  • transform-cli.awsstatic.com

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

  • *.s3.amazonaws.com

Se lavori in un ambiente con restrizioni Internet, aggiorna le regole del firewall per inserire questi URL nella lista consentita.

Installazione di AWS Trasforma la CLI

Il metodo di installazione consigliato è l'utilizzo dello script di installazione. Scegli la scheda per il tuo sistema operativo.

Per installare AWS Transform CLI

  1. Esegui lo script di installazione:

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

    Su Windows nativo, esegui lo script di installazione da Windows Terminal utilizzando PowerShell.

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

  2. Verifica l’installazione:

    atx --version

    Il comando dovrebbe visualizzare la versione installata di AWS Transform CLI.

Configurazione dell'autenticazione

AWS Transform custom richiede AWS credenziali per l'autenticazione con il servizio. Configura l'autenticazione utilizzando uno dei seguenti metodi.

Variabili di ambiente

Imposta le seguenti variabili di 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"

È inoltre possibile specificare un profilo utilizzando la variabile di AWS_PROFILE ambiente.

Linux and macOS
export AWS_PROFILE=your_profile_name
Windows (PowerShell)
$env:AWS_PROFILE="your_profile_name"
Nota

Le variabili di ambiente impostate con $env: in PowerShell si applicano solo alla sessione corrente. Per mantenerle permanenti tra le sessioni, impostale tramite Proprietà del sistema > Variabili d'ambiente o usa[System.Environment]::SetEnvironmentVariable().

AWS File delle credenziali

Configura le AWS credenziali nel file delle credenziali, disponibile in Linux e macOS o ~/.aws/credentials su Windows: %USERPROFILE%\.aws\credentials

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

Autorizzazioni IAM

AWS Le tue credenziali devono disporre delle autorizzazioni per chiamare il servizio personalizzato Transform. AWS Ti consigliamo di allegare la policy AWSTransformCustomFullAccess AWS gestita al tuo utente o ruolo IAM. Questa policy fornisce l'accesso completo a AWS Transform custom, inclusa l'autorizzazione a creare il ruolo collegato al servizio richiesto per l'emissione delle CloudWatch metriche sul tuo account.

Per un controllo più granulare, AWS Transform custom fornisce anche le seguenti politiche gestite: AWS

Per ulteriori informazioni su queste politiche, consulta le politiche AWS gestite per AWS Transform. Per le policy IAM personalizzate con autorizzazioni a livello di risorsa, consulta la AWS Transform Custom IAM Service Authorization Reference Guide.

Nota

  • Le definizioni di trasformazione sono AWS risorse con ARN (Amazon Resource Names). Puoi utilizzare le policy IAM per controllare l'accesso a trasformazioni o gruppi di trasformazioni specifici specificando l'ARN di trasformazione nelle dichiarazioni delle risorse delle tue policy IAM. I tag possono essere utilizzati per il controllo degli accessi raggruppati.

  • AWS IAM Identity Center è necessario per accedere a AWS Transform, ma non è necessario per utilizzare la CLI.

Configurazione AWS Region

AWS Transform custom è disponibile in AWS regioni specifiche e rileva automaticamente la configurazione della regione utilizzando la precedenza AWS CLI standard.

Regioni supportate

AWS Transform custom è disponibile nelle seguenti regioni: AWS

  • us-east-1(Stati Uniti orientali - Virginia settentrionale)

  • eu-central-1(Europa - Francoforte)

  • eu-west-2(Europa - Londra)

  • ca-central-1(Canada - Centrale)

  • ap-northeast-1(Asia Pacifico - Tokyo)

  • ap-northeast-2(Asia Pacifico - Seoul)

  • ap-southeast-2(Asia Pacifico - Sydney)

  • ap-south-1(Asia Pacifico - Mumbai)

Come viene determinata la regione

La CLI controlla queste fonti in ordine di priorità per determinare quale regione utilizzare:

  1. AWS_REGIONvariabile di ambiente (massima priorità)

  2. Variabile di ambiente AWS_DEFAULT_REGION

  3. Profilo selezionato nel file di AWS configurazione (tramite variabile di AWS_PROFILE ambiente)

  4. Profilo predefinito nel file di AWS configurazione

  5. Fallback predefinito a us-east-1 se non viene trovata alcuna configurazione

Nota

Il file di AWS configurazione si trova ~/.aws/config in Linux e macOS o %USERPROFILE%\.aws\config in Windows.

Nota

Se ATX_CUSTOM_ENDPOINT è impostata, la regione viene estratta dall'URL dell'endpoint e sovrascrive tutte le altre impostazioni.

Impostazione della regione

Scegli uno dei seguenti metodi per configurare la tua regione:

Opzione 1: variabile d'ambiente (consigliata per un uso temporaneo):

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

Opzione 2: configurazione AWS CLI (consigliata per la configurazione permanente): 

aws configure set region <your-region>

Opzione 3: Profile-specific configurazione:

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"

Opzione 4: modifica diretta dei file:

Modifica direttamente il file di AWS configurazione (~/.aws/configsu Linux e macOS o %USERPROFILE%\.aws\config su Windows):

[default]
region = <your-region>

[profile your_profile_name]
region = <your-region>

Verifica della configurazione della tua regione

Per verificare quale regione verrà utilizzata da AWS Transform custom:

Controlla l'impostazione attuale della regione: 

aws configure get region

Controlla le variabili di 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"

Visualizza la risoluzione dettagliata della regione nei log di debug:

Linux and macOS
tail -f ~/.aws/atx/logs/debug.log
Windows (PowerShell)
Get-Content "$env:USERPROFILE\.aws\atx\logs\debug.log" -Wait -Tail 10

Esempio di output del registro che mostra l'origine della regione:

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"
}

Il regionSource campo mostra da dove è stata derivata la regione (ad esempio, «aws-config (profile: default)», «AWS_REGION», «default»).

Importante

Se la configurazione della tua regione punta a una regione non supportata, la CLI mostrerà un chiaro messaggio di errore con le istruzioni per aggiornare la configurazione in una regione supportata.

Esecuzione della prima trasformazione

Il modo più veloce per iniziare è utilizzare una trasformazione AWS gestita. AWS Le trasformazioni gestite sono trasformazioni predefinite e AWS controllate pronte all'uso senza alcuna configurazione.

Per eseguire una trasformazione gestita in modo interattivo: AWS

atx

Quindi chiedi all'agente di eseguire una trasformazione:

Execute the AWS/java-aws-sdk-v1-to-v2 transformation on the codebase at ./my-java-project

Per eseguire una trasformazione in modo non interattivo: 

atx custom def exec -n AWS/java-aws-sdk-v1-to-v2 -p ./my-java-project -c "mvn clean install" -x -t

Per informazioni dettagliate sulle modalità di esecuzione, sulle opzioni di configurazione e sui flag di comando, vedere. Riferimento al comando

Comprensione dei risultati della trasformazione

Al termine di una trasformazione, AWS Transform custom fornisce un report che descrive i risultati. Se la trasformazione non è stata convalidata (ad esempio, una compilazione corretta per un'applicazione Java), il rapporto fornisce consigli per ulteriori azioni.

La maggior parte delle trasformazioni viene eseguita in più passaggi, utilizzando Git per eseguire il commit di quelli intermedi. Puoi rivedere le modifiche apportate dalla trasformazione usando i comandi Git standard:

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

Creazione di una trasformazione personalizzata

Quando le trasformazioni AWS gestite non soddisfano le tue esigenze, puoi creare trasformazioni personalizzate su misura per i tuoi requisiti specifici.

Per creare una trasformazione personalizzata

  1. Avvia AWS Transform CLI in modalità interattiva:

    atx

  2. Informa l'agente che desideri creare una nuova trasformazione e descrivi i tuoi requisiti.

  3. Fornisci materiali di riferimento come documentazione ed esempi di codice per migliorare la qualità.

  4. Testa e perfeziona la trasformazione in modo iterativo.

  5. Pubblicalo nel registro di trasformazione della tua organizzazione.

Per istruzioni dettagliate sulla creazione di trasformazioni personalizzate, consultaFlussi di lavoro.

AWS Trasforma l'applicazione Web (opzionale)

L'applicazione web AWS Transform è un'interfaccia opzionale per il monitoraggio di campagne di trasformazione su larga scala su più repository. Prima di utilizzare l'applicazione web AWS Transform, devi avere un'identità utente abilitata per accedere a AWS Transform nella tua organizzazione. Per informazioni sull'attivazione di AWS Transform, consulta Configurazione di AWS Transform.

Per utilizzare l'applicazione web AWS Transform:

  1. Visita https://aws.amazon.com/transform/ e accedi utilizzando le credenziali di AWS IAM Identity Center.

  2. Seleziona il tipo di job «Custom/code» nell'applicazione web AWS Transform.

  3. Indica all'agente il nome della definizione di trasformazione che desideri utilizzare.

  4. L'applicazione web fornisce un comando AWS Transform CLI che può essere condiviso con il tuo team. Questo comando richiama la definizione della trasformazione e registra i risultati dell'esecuzione nell'applicazione web.

  5. Dopo aver acquisito i risultati della trasformazione, visualizza le statistiche, le misurazioni del risparmio di tempo e fai domande sullo stato di avanzamento del tuo lavoro nella dashboard.

L'applicazione web è progettata per operazioni su scala aziendale in cui è necessario il monitoraggio centralizzato delle trasformazioni su più basi di codice.

Nota

AWS IAM Identity Center è necessario per accedere all'applicazione web Transform. AWS La CLI non richiede IAM Identity Center: sono necessarie solo AWS credenziali standard.