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à. # Configurazione dei client di servizio in AWS SDK for Java 2.x Per accedere a livello di codice Servizi AWS, l'SDK for Java 2.x utilizza un oggetto client per ciascuno. Servizio AWS Ad esempio, se la tua applicazione deve accedere ad Amazon EC2, crei un oggetto client Amazon EC2, un'istanza della classe Ec2Client, per interfacciarsi con [quel](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html) servizio. Quindi utilizzi il client di servizio per effettuare richieste in merito. Servizio AWS Per la maggior parte delle applicazioni, è possibile utilizzare un'[istanza singleton di un client di servizio](singleton-service-clients.md). Esistono molti modi per configurare il comportamento dell'SDK, ma alla fine tutto ha a che fare con il comportamento dei client di servizio. Qualsiasi configurazione non ha effetto finché il codice non crea un client di servizio che utilizza la configurazione. Esempi della configurazione fornita sono: + In che modo il codice si autentica AWS quando si chiama un servizio + Quindi Regione AWS vuoi che venga utilizzato da un client di servizio + Impostazioni di riprova e timeout per le chiamate di servizio + Configurazione di un proxy HTTP Consulta la [AWS SDKs Guida di riferimento agli strumenti](https://docs.aws.amazon.com/sdkref/latest/guide/) per le impostazioni, le funzionalità e altri concetti fondamentali comuni a molti di essi. AWS SDKs **Topics** + [Configurazione del client esternamente](configuring-service-clients-ext.md) + [Configurazione del client in codice](configuring-service-clients-code.md) + [Client di servizio Singleton](singleton-service-clients.md) + [Regione AWS](region-selection.md) + [Provider di credenziali](credentials.md) + [Tentativi](retry-strategy.md) + [Timeout](timeouts.md) + [Osservabilità](observability.md) + [Endpoint](endpoint-config.md) + [Configurare i client HTTP](http-configuration.md) + [Intercettori](interceptors.md) # Configurazione dei client di servizio per l'esterno AWS SDK for Java 2.x Molte impostazioni di configurazione possono essere gestite al di fuori del codice. Quando gestite la configurazione esternamente, questa può essere applicata a tutte le applicazioni nello stesso processo Java. La maggior parte delle impostazioni di configurazione può essere impostata come variabili di ambiente, proprietà del sistema JVM o in un file condiviso separato. AWS `config` Il `config` file condiviso può mantenere set di impostazioni separati, chiamati profili, per fornire configurazioni diverse per ambienti o test diversi. La maggior parte delle variabili di ambiente e delle impostazioni dei `config` file condivisi sono standardizzate e condivise tra strumenti AWS SDKs e strumenti per supportare funzionalità coerenti tra diversi linguaggi di programmazione e applicazioni. Nella maggior parte dei casi, le proprietà del sistema JVM che l'SDK for Java può utilizzare rispecchiano le variabili di ambiente. Consulta la *[Guida di riferimento agli strumenti AWS SDKs e](https://docs.aws.amazon.com/sdkref/latest/guide/overview.html)* scopri come configurare l'applicazione con questi metodi, oltre ai dettagli su ciascuna impostazione cross-sdk. *Per visualizzare tutte le impostazioni che l'SDK può risolvere dalle variabili di ambiente, dalle proprietà del sistema JVM o dai file di configurazione, consulta il [riferimento alle impostazioni nella Guida di riferimento](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) agli strumenti e agli strumenti.AWS SDKs * ## Catena di provider di configurazione per la configurazione del client L'SDK controlla diverse posizioni (o fonti) per trovare i valori di configurazione. 1. Qualsiasi impostazione esplicita impostata nel codice o su un client di servizio stesso ha la precedenza su qualsiasi altra cosa. 1. Proprietà del sistema JVM + *Per i dettagli sull'impostazione delle proprietà del sistema JVM, vedere [Come impostare le proprietà del sistema JVM nella and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/jvm-system-properties.html#jvm-sys-props-set).AWS SDKs * 1. Variabili di ambiente + Per i dettagli sull'impostazione delle variabili di ambiente, consulta le variabili di [ambiente](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) nella Guida di riferimento agli strumenti *AWS SDKs e* agli strumenti. + Nota che puoi configurare le variabili di ambiente per una shell a diversi livelli di ambito: a livello di sistema, a livello di utente e per una sessione di terminale specifica. 1. Condivisi e file `config` `credentials` + Per i dettagli sulla configurazione di questi file, consulta la *Guida di riferimento [Condivisi `config`AWS SDKs e `credentials` file](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in and Tools*. 1. Qualsiasi valore predefinito fornito dal codice sorgente SDK stesso viene utilizzato per ultimo. + Alcune proprietà, come Region, non hanno un valore predefinito. È necessario specificarle esplicitamente nel codice, in un'impostazione di ambiente o nel `config` file condiviso. Se l'SDK non è in grado di risolvere la configurazione richiesta, le richieste API possono avere esito negativo in fase di esecuzione. [Oltre a questa catena di configurazione generale, l'SDK for Java 2.x utilizza anche catene di provider specializzate, tra cui [la catena di fornitori di credenziali e Regione AWS la catena di provider](credentials-chain.md).](region-selection.md#default-region-provider-chain) Queste catene specializzate aggiungono provider aggiuntivi che tengono conto dell'ambiente in cui è in esecuzione l'SDK. Ad esempio, in un contenitore o in un'istanza EC2. ## Crea un client di servizio configurato utilizzando impostazioni esterne È necessario creare un client di servizio nell'applicazione per parlare con un Servizio AWS. I client di servizio sono il tuo punto di Servizi AWS contatto essenziale con cui gestire tutti i complessi dettagli di comunicazione in modo da non doverti preoccupare di loro. Si occupano automaticamente di attività importanti come la sicurezza, la gestione degli errori e i nuovi tentativi, consentendovi di concentrarvi sulla creazione dell'applicazione piuttosto che sulle complicazioni tecniche. ### Usa il metodo `create()` Se tutte le impostazioni di configurazione necessarie provengono da fonti esterne, puoi creare un client di servizio con un metodo semplice: ``` S3Client s3Client = S3Client.create(); ``` Il frammento di codice precedente crea un'`S3Client`istanza. Durante la creazione, l'SDK esamina le impostazioni nella catena di provider di configurazione. Una volta che l'SDK trova un valore di impostazione, il valore verrà utilizzato anche se esiste una configurazione successiva nella catena. Ad esempio, supponiamo che un utente imposti l'impostazione JVM per il Regione AWS impostando la proprietà di sistema. `-Daws.region=us-west-2` Se è impostata anche la variabile di `AWS_REGION` ambiente, il relativo valore viene ignorato. Nel processo di creazione verranno utilizzate anche la catena di fornitori di regioni predefinita e la catena di fornitori di credenziali predefinita. In qualche punto della catena, l'SDK deve definire le impostazioni da utilizzare e trovare le impostazioni che gli consentano di recuperare le credenziali per la firma delle richieste. Regione AWS Se i SDKs file riescono a trovare quei valori, la creazione del client fallisce. Sebbene sia possibile creare un client utilizzando questo pattern di creazione vuoto, in genere si utilizza questo modello quando si desidera [aggiungere la configurazione nel codice.](configuring-service-clients-code.md#conf-service-client-code-basic) ## Variabili di ambiente SDK for Java 2.x e proprietà del sistema JVM Oltre alle [impostazioni cross-sdk](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#settingsPages) supportate dalla maggior parte AWS SDKs, l'SDK for Java 2.x fornisce le seguenti impostazioni. **Nota** Queste variabili di ambiente e le proprietà del sistema JVM sono destinate principalmente a casi d'uso avanzati, test o scenari di distribuzione specifici. Nella maggior parte del codice applicativo, è preferibile utilizzare le opzioni di configurazione programmatica fornite dai client builder dell'SDK per una maggiore sicurezza dei tipi e un supporto IDE migliori. ### Variabili di ambiente del provider di credenziali di contenitore Oltre alle variabili di ambiente standard per le credenziali dei container documentate nella guida di riferimento, l'SDK supporta anche: `AWS_CONTAINER_SERVICE_ENDPOINT`—Questa variabile di ambiente specifica l'endpoint per il servizio di metadati del contenitore quando si utilizza il provider di credenziali del contenitore. Proprietà del sistema Java: `aws.containerServiceEndpoint` Valore predefinito: `http://169.254.170.2` ### Variabili di ambiente di implementazione del client HTTP `SYNC_HTTP_SERVICE_IMPL`: identifica in modo esplicito l'[implementazione HTTP sincrona predefinita che verrà utilizzata dall'SDK](http-configuration.md#http-config-sync). Ciò è utile quando sono presenti più implementazioni sul classpath o per ottimizzare le prestazioni, poiché la scoperta dell'implementazione richiede la scansione del classpath. Proprietà del sistema Java: `software.amazon.awssdk.http.service.impl` `ASYNC_HTTP_SERVICE_IMPL`: identifica in modo esplicito l'implementazione [HTTP asincrona](http-configuration.md#http-config-async) predefinita che verrà utilizzata dall'SDK. Ciò è utile quando sono presenti più implementazioni sul classpath o per ottimizzare le prestazioni poiché la scoperta dell'implementazione richiede la scansione del classpath. Proprietà del sistema Java: `software.amazon.awssdk.http.async.service.impl` # Configurazione dei client di servizio nel codice per AWS SDK for Java 2.x In alternativa o in aggiunta alla configurazione [esterna dei client di servizio, è possibile configurarli a livello di codice a livello](configuring-service-clients-ext.md) di codice. Configurando i client di servizio in codice, acquisisci un controllo approfondito delle numerose opzioni a tua disposizione. La maggior parte delle configurazioni che è possibile impostare esternamente possono essere impostate anche nel codice. ## Configurazione di base in codice Ad esempio, lo snippet seguente imposta il codice Regione AWS `EU_SOUTH_2` per un client di servizio Amazon S3: ``` S3Client s3Client = S3Client.builder() .region(Region.EU_SOUTH_2) .build(); ``` Lo snippet precedente mostra il metodo statico di fabbrica,. `builder()` Il `builder()` metodo restituisce un `builder` oggetto che consente di personalizzare il client del servizio. I metodi fluent setter restituiscono l'`builder`oggetto, in questo caso un'[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3ClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3ClientBuilder.html)istanza, in modo da poter concatenare le chiamate ai metodi per comodità e per rendere il codice più leggibile. Dopo aver configurato le proprietà desiderate, chiamate il metodo per creare il client. `build()` ## Configurazione avanzata in codice Il seguente frammento mostra opzioni di configurazione aggiuntive: ``` ClientOverrideConfiguration clientOverrideConfiguration = ClientOverrideConfiguration.builder() .apiCallAttemptTimeout(Duration.ofSeconds(1)) .addMetricPublisher(CloudWatchMetricPublisher.create()) .build(); S3Client s3Client = S3Client.builder() .region(Region.EU_SOUTH_2) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .overrideConfiguration(clientOverrideConfiguration) .httpClientBuilder( ApacheHttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://proxy:8080")) .build()) ).build(); ``` Nel frammento precedente, puoi vedere diversi punti di accesso per configurare un client di servizio: + [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.Builder.html) che fornisce opzioni di configurazione comuni a tutti i client di servizio. Queste impostazioni sono comportamenti AWS specifici indipendenti da qualsiasi implementazione HTTP. + **Configurazione del client HTTP tramite un'implementazione separata di HTTP Client Builder.** `ApacheHttpClient.Builder`Questo è un esempio. Il client di servizio fornisce il `httpClientBuilder()` metodo per associare il client HTTP configurato al client di servizio. + **Metodi presenti nel [client builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3ClientBuilder.html) stesso,** ad esempio e `region()` `credentialsProvider()` ### Stessa configurazione utilizzando blocchi di configurazione Invece di creare oggetti separati e poi passarli ai metodi del client di servizio, AWS SDK for Java 2.x fornisce metodi che accettano espressioni lambda per creare questi oggetti in linea. I metodi di configurazione del builder hanno lo stesso nome, ma hanno firme diverse. Esempio: + [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(software.amazon.awssdk.core.client.config.ClientOverrideConfiguration)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(software.amazon.awssdk.core.client.config.ClientOverrideConfiguration)) + [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(java.util.function.Consumer)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(java.util.function.Consumer)) La configurazione del client S3 mostrata in precedenza utilizzando questo approccio può essere eseguita in un unico blocco di codice: ``` S3Client s3Client = S3Client.builder() .region(Region.EU_SOUTH_2) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .overrideConfiguration(b -> b .apiCallAttemptTimeout(Duration.ofSeconds(1)) .addMetricPublisher(CloudWatchMetricPublisher.create())) .httpClientBuilder(ApacheHttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://proxy:8080")) .build())) .build(); ``` ## Opzioni di configurazione non disponibili nel codice Poiché le seguenti impostazioni influiscono sui processi di inizializzazione fondamentali nell'SDK, puoi impostare le seguenti impostazioni di configurazione solo esternamente e non nel codice: ### Impostazioni della posizione dei file Queste impostazioni controllano la posizione dei file di configurazione e credenziali condivisi e non possono essere sovrascritte a livello di codice dopo averli caricati dall'SDK: + **AWS\$1CONFIG\$1FILE (variabile di ambiente)/AWS.configFile** **(proprietà del sistema JVM)** + **AWS\$1SHARED\$1CREDENTIALS\$1FILE** **(variabile di ambiente)/aws. sharedCredentialsFile** (proprietà del sistema JVM) Queste impostazioni devono essere impostate prima che l'SDK carichi i file di configurazione, poiché determinano dove l'SDK cerca la configurazione. Una volta inizializzato l'SDK, la modifica di questi valori non ha alcun effetto. ### Disattivazione del servizio di metadati dell'istanza + **AWS\$1EC2\$1METADATA\$1DISABLED (variabile di ambiente)/aws.disableEC2Metadata** **(proprietà del sistema JVM)** Questa impostazione controlla se l'SDK tenta o meno di utilizzare l'EC2 Instance Metadata Service. Una volta inizializzato l'SDK, non è possibile modificare questa impostazione a livello di codice. ### Selezione del profilo + **AWS\$1PROFILE**(variabile di ambiente)/**aws.profile** (proprietà del sistema JVM) Questa impostazione indica all'SDK quale profilo caricare dai file di configurazione e credenziali condivisi. Una volta caricato, la modifica di questo valore non ha alcun effetto. ### Percorsi delle credenziali del contenitore + **AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI** + **AWS\$1CONTAINER\$1CREDENZIALI\$1COMPLETE\$1URI** + **AWS\$1CONTAINER\$1TOKEN DI AUTORIZZAZIONE** + **AWS\$1CONTAINERFILE\$1TOKEN\$1DI \$1AUTORIZZAZIONE** Utilizzate queste variabili di ambiente per indicare all'SDK come recuperare le credenziali dai servizi del contenitore. Dopo aver stabilito la catena di fornitori di credenziali durante l'inizializzazione del client di servizio, non è possibile modificare queste impostazioni. ### Selezione predefinita dell'implementazione HTTP + **SYNC\$1HTTP\$1SERVICE\$1IMPL (variabile di ambiente)/software.amazon.awssdk.http.service.impl (proprietà** **del sistema JVM)** + **ASYNC\$1HTTP\$1SERVICE\$1IMPL (variabile di ambiente)/**software.amazon.awssdk.http.async.service.impl**** (proprietà di sistema JVM) Queste impostazioni globali determinano l'implementazione del client HTTP utilizzata dall'SDK per tutti i client di servizio, a meno che non venga sovrascritta nel codice per i singoli client di servizio. È necessario impostarle prima che l'SDK inizializzi i suoi client HTTP e non possono essere modificate in seguito. # Usa le istanze del client del servizio singleton con AWS SDK for Java 2.x I client di servizio in the AWS SDK for Java 2.x sono thread-safe. È possibile creare un'istanza di ogni client di servizio e riutilizzarla in tutta l'applicazione. Questo approccio migliora le prestazioni e gestisce le risorse in modo più efficiente. ## Vantaggi dei clienti del servizio Singleton Pooling di connessioni I client di servizio gestiscono pool di connessioni HTTP interni. Creare e distruggere questi pool è costoso. Quando si riutilizzano i client, questi pool vengono condivisi in modo efficiente tra le richieste. Sovraccarico di inizializzazione ridotto La creazione di un client implica il caricamento della configurazione, la creazione di credenziali e l'inizializzazione dei componenti interni. Le istanze Singleton eliminano questo sovraccarico. Migliore utilizzo delle risorse I client Singleton impediscono l'esaurimento delle risorse che può verificarsi quando si creano molte istanze client. ## Crea e utilizza i client di servizio Singleton L'esempio seguente mostra come creare e utilizzare i client di servizio singleton: ``` // Create one instance and use it throughout the application. public class ServiceClientSource { private static final S3Client s3Client = S3Client.create(); public static S3Client getS3Client() { return s3Client; } } ``` Non creare nuovi client per ogni operazione: ``` // This approach creates unnecessary overhead. public void badExample() { try (S3Client s3 = S3Client.create()) { s3.listBuckets(); } } ``` ## Considerazioni importanti + I client di servizio sono thread-safe. Puoi condividerli in sicurezza su più thread. + Chiudi i client solo quando l'applicazione si spegne o se non hai più bisogno del client. Usa `client.close()` o try-with-resources a livello di applicazione. + Se hai bisogno di configurazioni diverse, come regioni o credenziali, crea istanze singleton separate per ogni configurazione. Se utilizzi framework di iniezione delle dipendenze come Spring, configura i client di servizio come bean singleton. Ciò garantisce una corretta gestione del ciclo di vita. # Impostazione del Regione AWS per AWS SDK for Java 2.x I client SDK si connettono Servizio AWS a un indirizzo specifico Regione AWS specificato al momento della creazione del client. Questa configurazione consente all'applicazione di interagire con AWS le risorse in quell'area geografica. Quando crei un client di servizio senza impostare esplicitamente una regione, l'SDK utilizza la regione predefinita della configurazione esterna. ## Configura esplicitamente un Regione AWS [Per impostare in modo esplicito una regione, si consiglia di utilizzare le costanti definite nella classe Region.](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/Region.html) Si tratta di un'enumerazione di tutte le regioni disponibili pubblicamente. Per creare un client con una regione enumerata dalla classe, utilizzate il metodo del client builder. `region` ``` Ec2Client ec2 = Ec2Client.builder() .region(Region.US_WEST_2) .build(); ``` Se la regione che desideri utilizzare non è una delle enumerazioni della `Region` classe, puoi creare una nuova regione utilizzando il metodo statico. `of` Questo metodo consente di accedere a nuove regioni senza aggiornare l'SDK. ``` Region newRegion = Region.of("us-east-42"); Ec2Client ec2 = Ec2Client.builder() .region(newRegion) .build(); ``` **Nota** *Dopo aver creato un client con il builder, è *immutabile* e non può essere modificato. Regione AWS * Se devi lavorare con più client Regioni AWS per lo stesso servizio, devi creare più client, uno per regione. ## Consenti all'SDK di determinare automaticamente l'impostazione predefinita dall'ambiente Regione AWS Quando il codice viene eseguito su Amazon EC2 o AWS Lambda, potresti voler configurare i client in modo Regione AWS che utilizzino lo stesso su cui è in esecuzione il codice. Questo disaccoppia il codice dall'ambiente in cui è in esecuzione e semplifica la distribuzione dell'applicazione su più utenti Regioni AWS per ridurre la latenza o la ridondanza. Per utilizzare la catena di Regione AWS provider predefinita per determinare la regione dall'ambiente, utilizzate il metodo del client builder. `create` ``` Ec2Client ec2 = Ec2Client.create(); ``` Puoi anche configurare il client in altri modi, ma non impostare la regione. L'SDK rileva Regione AWS utilizzando la catena di provider regionali predefinita: ``` Ec2Client ec2Client = Ec2Client.builder() .credentialsProvider(ProfileCredentialsProvider.builder() .profileName("my-profile") .build()) .build(); ``` Se non ne imposti uno in modo esplicito Regione AWS utilizzando il `region` metodo, l'SDK consulta la catena di provider di regioni predefinita per determinare la regione da utilizzare. ### Comprendere la catena di provider predefinita Regione AWS **L'SDK esegue le seguenti operazioni per cercare un Regione AWS:** 1. Qualsiasi regione esplicita impostata utilizzando il `region` metodo sul builder stesso ha la precedenza su qualsiasi altra cosa. 1. L'SDK cerca la proprietà del sistema JVM `aws.region` e, se trovata, ne utilizza il valore. 1. La variabile di ambiente `AWS_REGION` è selezionata. Se è impostata, quella regione viene utilizzata per configurare il client. **Nota** Il Lambda contenitore imposta questa variabile di ambiente. 1. L'SDK controlla il profilo attivo nei file di [configurazione e credenziali AWS condivisi](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). Se la `region` proprietà è presente, l'SDK la utilizza. Il `default` profilo è il profilo attivo a meno che non venga sovrascritto dalla variabile di `AWS_PROFILE` ambiente o dalla proprietà del sistema `aws.profile` JVM. Se l'SDK trova la `region` proprietà in entrambi i file per lo stesso profilo (incluso il `default` profilo), l'SDK utilizza il valore nel file delle credenziali condivise. 1. L'SDK tenta di utilizzare il servizio di metadati dell' Amazon EC2 istanza (IMDS) per determinare la regione dell'istanza attualmente in esecuzione. Amazon EC2 + Per una maggiore sicurezza, dovresti disattivare l'SDK dal tentativo di utilizzare la versione 1 di IMDS. Per disabilitare la versione 1, si utilizza la stessa impostazione descritta nella sezione. [Acquisisci in modo sicuro le credenziali dei ruoli IAM](ec2-iam-roles.md#securely-read-IAM-role_credentials) 1. Se l'SDK non ha ancora trovato una regione a questo punto, la creazione del client fallisce con un'eccezione. Quando si sviluppano AWS applicazioni, un approccio comune consiste nell'utilizzare il *file di configurazione condiviso* per impostare la regione per lo sviluppo locale e affidarsi alla catena di provider di regioni predefinita per determinare la regione quando l'applicazione viene eseguita sull' AWS infrastruttura. Questo semplifica notevolmente la creazione del client e mantiene l'applicazione portatile. ## Verifica se un servizio è disponibile in una regione Per vedere se un particolare Servizio AWS è disponibile in una regione, usa il `serviceMetadata` metodo statico su un client di servizio: ``` DynamoDbClient.serviceMetadata().regions().forEach(System.out::println); ``` Lo snippet precedente stampa un lungo elenco di Regione AWS codici che dispongono del servizio DynamoDB: ``` af-south-1 ap-east-1 ap-northeast-1 ap-northeast-2 ap-northeast-3 ap-south-1 ap-south-2 ap-southeast-1 ... ``` È possibile utilizzare un codice per cercare l'[enumerazione delle classi Region per la regione](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/Region.html) da utilizzare dal client di servizio. Ad esempio, se vuoi lavorare con DynamoDB nella regione con il `ap-northeast-2` codice, crea il tuo client DynamoDB con almeno la seguente configurazione: ``` DynamoDbClient ddb = DynamoDbClient.builder() .region(Region.AP_NORTHEAST_2) .build(); ``` ## Scegli un endpoint specifico In determinate situazioni, ad esempio per testare in anteprima le funzionalità di un servizio prima che queste diventino disponibili sul mercato, potrebbe essere necessario specificare un endpoint specifico in una regione. In queste situazioni, i client del servizio possono essere configurati chiamando il metodo. `endpointOverride` Ad esempio, per configurare un Amazon EC2 client in modo che utilizzi la regione Europa (Irlanda) con un endpoint specifico, usa il codice seguente. ``` Ec2Client ec2 = Ec2Client.builder() .region(Region.EU_WEST_1) .endpointOverride(URI.create("https://ec2.eu-west-1.amazonaws.com")) .build(); ``` Vedi [Regioni ed endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html) per l'elenco corrente delle regioni e gli endpoint corrispondenti per tutti i servizi. AWS # Utilizzo dei provider di credenziali in AWS SDK for Java 2.x Il ruolo di un fornitore di credenziali in the AWS SDK for Java 2.x è quello di reperire e fornire credenziali ai client dell'SDK. Servizio AWS L'SDK utilizza le credenziali che ottiene per autenticarsi con il servizio firmando crittograficamente ogni richiesta. Le credenziali di solito sono costituite da chiavi di accesso: un ID della chiave di accesso e una chiave di accesso segreta insieme. Quando si utilizzano credenziali temporanee, che vengono utilizzate quando si configura la [configurazione del provider di token SSO](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-token-config) o si configura il runtime per [assumere un ruolo IAM (AWS Identity and Access Management)](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#credOrSourceAssumeRole) come esempio, viene aggiunto un token di sessione alle chiavi di accesso, che fornisce un accesso limitato nel tempo alle risorse. AWS In questo argomento vengono descritti diversi modi per abilitare l'SDK per accedere alle credenziali. **Topics** + [Lavori di sviluppo interattivi](credentials-temporary.md) + [Catena di fornitori di credenziali predefinita](credentials-chain.md) + [Memorizzazione nella cache delle credenziali](credential-caching.md) + [Specificare un provider di credenziali specifico](credentials-providers.md) + [Usa profili di configurazione condivisi](credentials-profiles.md) + [Utilizzare un processo esterno](credentials-process.md) + [Fornire le credenziali nel codice](credentials-explicit.md) + [Leggi le credenziali del ruolo IAM su Amazon EC2](ec2-iam-roles.md) # Credenziali di accesso per il lavoro di sviluppo interattivo utilizzando AWS SDK for Java 2.x Per una maggiore sicurezza, si AWS consiglia di configurare l'SDK for Java in modo [da utilizzare credenziali temporanee](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) anziché credenziali di lunga durata. Le credenziali temporanee sono costituite da chiavi di accesso (ID chiave di accesso e chiave di accesso segreta) e un token di sessione. Sono disponibili diversi approcci per lavorare con credenziali temporanee. L'approccio utilizzato, e quindi la configurazione fornita all'SDK, dipende dal caso d'uso. Quando svolgi attività di sviluppo interattive con Java SDK, ti consigliamo di utilizzare le credenziali di accesso alla AWS Console. ## Utilizzo delle credenziali di accesso alla console È possibile utilizzare le credenziali di accesso esistenti AWS della Console di gestione per l'accesso programmatico ai servizi. AWS Dopo un flusso di autenticazione basato su browser, AWS genera credenziali temporanee che funzionano con strumenti di sviluppo locali come SDK for AWS CLI Java 2.x. Con questo processo, puoi autenticarti utilizzando le credenziali root create durante la configurazione iniziale dell'account, un utente IAM o un'identità federata del tuo provider di identità e gestire automaticamente le AWS CLI credenziali temporanee per te. Questo approccio migliora la sicurezza eliminando la necessità di archiviare le credenziali a lungo termine a livello locale. Quando si esegue il `aws login` comando, è possibile selezionare una delle sessioni attive della console oppure accedere tramite il flusso di autenticazione basato sul browser e questo genererà automaticamente credenziali temporanee. L'SDK for Java 2.x aggiornerà automaticamente queste credenziali per un massimo di 12 ore. **Importante** Oltre alla configurazione impostata nel file di configurazione condiviso che funziona per tutti i progetti, ogni singolo progetto Java richiede la seguente dipendenza nel file Maven: `pom.xml` ``` software.amazon.awssdk signin ``` La `signin` dipendenza fornisce il codice che consente all'SDK for Java 2.x di accedere e utilizzare le credenziali di accesso alla console. *Per ulteriori informazioni sui prerequisiti, sull'accesso e sulla disconnessione, consulta [Accesso per lo sviluppo AWS locale utilizzando le credenziali della console](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) nella Guida di riferimento all'SDK and Tools.AWS * ## Single-sign-on approccio Quando svolgi attività di sviluppo interattive con Java SDK, in alternativa puoi utilizzare l'approccio Single Sign-On. Questo approccio richiede la seguente configurazione: + [Configurazione tramite IAM Identity Center](get-started-auth.md#setup-auth) + [Configura un profilo nel file di configurazione AWS condiviso](get-started-auth.md#setup-credentials) + utilizzando AWS CLI ed [eseguendo un comando](get-started-auth.md#setup-login-sso) per accedere e creare una sessione attiva ### configurazione IAM Identity Center Quando configuri l'SDK per utilizzare l'accesso Single Sign-On di IAM Identity Center come descritto [Panoramica della configurazione](setup.md#setup-overview) in questa guida, l'SDK utilizza credenziali temporanee. L'SDK utilizza il token di accesso IAM Identity Center per accedere al ruolo IAM configurato con l'impostazione nel file. `sso_role_name` `config` L'SDK assume questo ruolo IAM e recupera le credenziali temporanee per firmare le richieste. Servizio AWS Per maggiori dettagli su come l'SDK ottiene le credenziali temporanee dalla configurazione, consulta la sezione [Understanding IAM Identity Center sull'autenticazione](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) della and Tools Reference Guide. AWS SDKs **Importante** Oltre alla configurazione impostata nel `config` file condiviso che funziona per tutti i progetti, ogni singolo progetto Java richiede le seguenti dipendenze nel file Maven: `pom.xml` ``` software.amazon.awssdk sso software.amazon.awssdk ssooidc ``` Le `ssooidc` dipendenze `sso` e forniscono il codice che consente all'SDK for Java 2.x di accedere alle credenziali temporanee. ### Recupera le credenziali temporanee dal portale di accesso AWS In alternativa alla configurazione Single Sign-On di IAM Identity Center, puoi copiare e utilizzare le credenziali temporanee disponibili nel portale di accesso. AWS È possibile utilizzare le credenziali temporanee in un profilo o utilizzarle come valori per le proprietà di sistema e le variabili di ambiente. **Configura un file di credenziali locale per credenziali temporanee** 1. [Crea un file di credenziali condiviso](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) 1. Nel file delle credenziali, incolla il seguente testo segnaposto fino a incollare le credenziali temporanee funzionanti. ``` [default] aws_access_key_id= aws_secret_access_key= aws_session_token= ``` 1. Salvare il file. Il file `~/.aws/credentials` dovrebbe ora esistere sul tuo sistema di sviluppo locale. Questo file contiene il [profilo [predefinito]](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile) utilizzato dall'SDK for Java se non viene specificato un profilo denominato specifico. 1. [Accedi al portale di AWS accesso](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosignin.html) 1. Segui queste istruzioni sotto l'intestazione [Aggiornamento manuale delle credenziali](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html#how-to-get-temp-credentials) per copiare le credenziali del ruolo IAM dal AWS portale di accesso. 1. Per la fase 2 delle istruzioni collegate, scegli `Access keys` il nome del ruolo IAM che concede l'accesso per le tue esigenze di sviluppo. Questo ruolo in genere ha un nome simile **PowerUserAccess**a **Developer**. 1. Nella finestra di dialogo modale, selezionate il sistema operativo in uso e copiate il contenuto da **Aggiungi un profilo al file delle AWS credenziali**. 1. Incolla le credenziali copiate nel `credentials` file locale e rimuovi il nome del profilo generato. Il file dovrebbe essere simile al seguente. ``` [default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` 1. Salvare il file `credentials`. Quando l'SDK for Java crea un client di servizio, accederà a queste credenziali temporanee e le utilizzerà per ogni richiesta. Le impostazioni per il ruolo IAM scelto nella fase 5a [determinano la durata di validità delle credenziali temporanee](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html). La durata massima è di dodici ore. Dopo la scadenza delle credenziali temporanee, ripeti i passaggi da 4 a 7. # Catena di fornitori di credenziali predefinita in AWS SDK for Java 2.x La catena di provider di credenziali predefinita cerca AWS SDK for Java 2.x automaticamente le AWS credenziali in una sequenza di posizioni predefinita, consentendo alle applicazioni di autenticarsi senza specificare esplicitamente Servizi AWS le fonti delle credenziali. La catena di provider di credenziali predefinita è implementata dalla classe. [DefaultCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html) Delega in sequenza ad altri provider di credenziali le implementazioni che controllano la configurazione in varie posizioni. Il primo provider di credenziali in grado di trovare tutti gli elementi di configurazione necessari causa la fine della catena. Per utilizzare la catena di fornitori di credenziali predefinita per fornire credenziali temporanee, create un service client builder ma non specificate un provider di credenziali. Il seguente frammento di codice crea una catena `DynamoDbClient` che utilizza la catena di provider di credenziali predefinita per individuare e recuperare le impostazioni di configurazione. ``` // Any external Region configuration is overridden. // The SDK uses the default credentials provider chain because no specific credentials provider is specified. Region region = Region.US_WEST_2; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .build(); ``` ## Ordine di recupero delle impostazioni delle credenziali La catena di provider di credenziali predefinita di SDK for Java 2.x cerca la configurazione nell'ambiente utilizzando una sequenza predefinita. 1. Proprietà del sistema Java + L'SDK utilizza la [SystemPropertyCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/SystemPropertyCredentialsProvider.html)classe per caricare credenziali temporanee dalle proprietà di sistema `aws.accessKeyId``aws.secretAccessKey`, e `aws.sessionToken` Java. **Nota** Per informazioni su come impostare le proprietà del sistema Java, consultate il tutorial [System Properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) sul sito Web ufficiale di *Java Tutorials*. 1. Variabili di ambiente + L'SDK utilizza la [EnvironmentVariableCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/EnvironmentVariableCredentialsProvider.html)classe per caricare credenziali temporanee dalle variabili di ambiente `AWS_ACCESS_KEY_ID``AWS_SECRET_ACCESS_KEY`, e. `AWS_SESSION_TOKEN` 1. Token di identità Web e ARN del ruolo IAM + L'SDK utilizza la [WebIdentityTokenFileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/WebIdentityTokenFileCredentialsProvider.html)classe per caricare le credenziali assumendo un ruolo utilizzando un token di identità web. + Il provider di credenziali cerca le seguenti variabili di ambiente o proprietà del sistema JVM: + `AWS_WEB_IDENTITY_TOKEN_FILE or aws.webIdentityTokenFile` + `AWS_ROLE_ARN` o `aws.roleArn` + `AWS_ROLE_SESSION_NAME`o `aws.roleSessionName` (opzionale) + Dopo aver acquisito i valori, l'SDK chiama AWS Security Token Service (STS) e utilizza le credenziali temporanee restituite per firmare le richieste. + Gli ambienti di runtime come Amazon Elastic Kubernetes Service (EKS) rendono automaticamente disponibili i token di identità Web, consentendo AWS SDKs alle applicazioni di ottenere credenziali temporanee. AWS 1. `config`I file condivisi e `credentials` + L'SDK li utilizza [ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html)per caricare le impostazioni Single Sign-on o le credenziali temporanee di IAM Identity Center dal `[default]` profilo nei file condivisi e nei file. `credentials` `config` La AWS SDKs and Tools Reference Guide contiene [informazioni dettagliate](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html#idccredres) su come l'SDK for Java funziona con il token single sign-on IAM Identity Center per ottenere le credenziali temporanee che l'SDK utilizza per chiamare. Servizi AWS **Nota** I `config` file `credentials` e sono condivisi da vari strumenti. AWS SDKs Per ulteriori informazioni, vedere [The. aws/credentials and .aws/config](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)file nella AWS SDKs and Tools Reference Guide. + Poiché un profilo condiviso `credentials` e `config` i file possono contenere molti set diversi di impostazioni, i membri `ProfileCredentialsProvider` delegano a una serie di altri provider il compito di cercare le impostazioni all'interno del `[default]` profilo: + **Credenziali del token di identità Web** (classe`WebIdentityTokenCredentialsProvider`): quando il profilo contiene `role_arn` e. `web_identity_token_file` + **Credenziali SSO** (classe`SsoCredentialsProvider`): quando il profilo contiene proprietà relative a SSO come,. `sso_role_name` `sso_account_id` + **Credenziali basate sui ruoli con profilo di origine (classe`StsAssumeRoleCredentialsProvider`): quando il profilo** contiene e. `role_arn` `source_profile` + **Credenziali basate sui ruoli con origine delle credenziali** (classe`StsAssumeRoleWithSourceCredentialsProvider`): quando il profilo contiene e. `role_arn` `credential_source` + Quando`credential_source = Environment`: utilizza una catena di e `SystemPropertyCredentialsProvider` `EnvironmentVariableCredentialsProvider` + Quando`credential_source = Ec2InstanceMetadata`: utilizza `InstanceProfileCredentialsProvider` + Quando`credential_source = EcsContainer`: utilizza `ContainerCredentialsProvider` + **Credenziali di accesso alla console** (classe`LoginCredentialsProvider`): quando il profilo contiene `login_session` + **Credenziali di processo** (classe`ProcessCredentialsProvider`): quando il profilo contiene. `credential_process` + **Credenziali di sessione** (classe`StaticSessionCredentialsProvider`): quando il profilo contiene `aws_access_key_id``aws_secret_access_key`, e. `aws_session_token` + **Credenziali di base** (classe`StaticCredentialsProvider`): quando il profilo contiene `aws_access_key_id` e. `aws_secret_access_key` 1. Amazon ECS credenziali del contenitore + L'SDK utilizza la [ContainerCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ContainerCredentialsProvider.html)classe per caricare le credenziali temporanee utilizzando le seguenti variabili di ambiente: 1. `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` o `AWS_CONTAINER_CREDENTIALS_FULL_URI` 1. `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` o `AWS_CONTAINER_AUTHORIZATION_TOKEN` L'agente contenitore ECS imposta automaticamente la variabile di `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` ambiente, che punta all'endpoint delle credenziali ECS. Le altre variabili di ambiente sono in genere impostate in scenari specifici in cui non viene utilizzato l'endpoint di credenziali ECS standard. 1. Amazon EC2 istanza: credenziali fornite dal ruolo IAM + L'SDK utilizza la [InstanceProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProvider.html)classe per caricare credenziali temporanee dal servizio di metadati. Amazon EC2 1. Se l'SDK non riesce a trovare le impostazioni di configurazione necessarie attraverso tutti i passaggi sopra elencati, genera un'eccezione con un output simile al seguente: ``` software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers in the chain AwsCredentialsProviderChain(credentialsProviders=[SystemPropertyCredentialsProvider(), EnvironmentVariableCredentialsProvider(), WebIdentityTokenCredentialsProvider(), ProfileCredentialsProvider(), ContainerCredentialsProvider(), InstanceProfileCredentialsProvider()]) ``` ## Usa il codice in `DefaultCredentialsProvider` Puoi utilizzare in modo esplicito la catena di fornitori di credenziali predefinita nel tuo codice. Dal punto di vista funzionale, ciò equivale a non specificare affatto un provider di credenziali, poiché l'SDK lo utilizza per impostazione predefinita. `DefaultCredentialsProvider` Tuttavia, utilizzarlo in modo esplicito può rendere il codice più leggibile e autodocumentante. Mostra chiaramente l'intenzione di utilizzare la catena di credenziali predefinita. ``` import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; public class ExplicitDefaultCredentialsExample { public static void main(String[] args) { // Explicitly create the DefaultCredentialsProvider. DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider .builder().build(); // Use it with any service client. S3Client s3Client = S3Client.builder() .region(Region.US_WEST_2) .credentialsProvider(defaultCredentialsProvider) .build(); // Now you can use the client with the default credentials chain. s3Client.listBuckets(); } } ``` Quando crei il provider di credenziali predefinito, puoi fornire ulteriori configurazioni: ``` DefaultCredentialsProvider customizedProvider = DefaultCredentialsProvider.builder() .profileName("custom-profile") // Use a specific profile if the chain gets to the `ProfileCredentialsProvider` stage. .asyncCredentialUpdateEnabled(true) // Enable async credential updates. .build(); ``` Questo approccio offre un maggiore controllo pur garantendo la comodità della catena di credenziali predefinita. # Memorizzazione nella cache delle credenziali in AWS SDK for Java 2.x AWS SDK for Java 2.x Implementa la memorizzazione nella cache delle credenziali per migliorare le prestazioni e ridurre le chiamate alle fonti delle credenziali. Questa sezione spiega come funziona la memorizzazione nella cache delle credenziali e come configurarla per le applicazioni. ## Comprendere la memorizzazione nella cache dei provider di credenziali I provider di credenziali nell'SDK for Java 2.x utilizzano diverse strategie di caching: + Memorizzazione nella cache **interna delle credenziali: molti provider memorizzano nella cache** le credenziali recuperate. + **Aggiornamento automatico: i provider con credenziali memorizzate nella cache implementano meccanismi di aggiornamento**. ### Provider con memorizzazione nella cache delle credenziali interne I seguenti provider di credenziali memorizzano le credenziali internamente, anche quando si creano nuove istanze: + **Provider di credenziali del profilo di istanza**: memorizza nella cache le credenziali dal servizio di metadati Amazon EC2. + **Provider di credenziali del contenitore**: memorizza nella cache le credenziali dall'endpoint dei metadati del contenitore. + **Provider basati su STS**: memorizza nella cache le credenziali temporanee di (STS). AWS Security Token Service + **Fornitori di token di identità Web**: memorizza nella cache le credenziali ottenute dai token di identità Web. + **Provider di credenziali di processo**: memorizza nella cache le credenziali provenienti da processi esterni. ### Provider senza memorizzazione nella cache interna I seguenti provider non implementano la memorizzazione nella cache interna: + **Provider di credenziali variabili d'ambiente** + **Provider di credenziali di proprietà del sistema** + **Provider di credenziali statiche** ## Configurazione della memorizzazione nella cache delle credenziali Puoi personalizzare il comportamento di memorizzazione nella cache durante la creazione di provider di credenziali: ### Tempo stantio Controlla quando le credenziali sono considerate obsolete e devono essere aggiornate: ``` .staleTime(Duration.ofMinutes(2)) // Consider stale 2 minutes before expiration. ``` ### Ora di prefetch Determina quando iniziare ad aggiornare le credenziali prima della scadenza: ``` .prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration. ``` ### Aggiornamenti asincroni Abilita l'aggiornamento delle credenziali in background: ``` .asyncCredentialUpdateEnabled(true) // Refresh credentials in background thread. ``` ### Durata della sessione Per i provider basati su STS, controlla per quanto tempo le credenziali temporanee rimangono valide: ``` .refreshRequest(r -> r.durationSeconds(3600)) // 1 hour session. ``` ## Esempio di configurazione delle credenziali di memorizzazione nella cache Come esempio di configurazione della memorizzazione nella cache per un'implementazione di un provider di credenziali, potresti voler fare in modo che l'SDK utilizzi un thread in background per prerecuperare (recuperare in anticipo) le credenziali prima che scadano. In questo modo puoi evitare la chiamata di blocco che recupera nuove credenziali. Di seguito viene mostrato un esempio che crea un file `[StsAssumeRoleCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsAssumeRoleCredentialsProvider.html)` che utilizza un thread in background per prerecuperare le credenziali impostando la `[asyncCredentialUpdateEnabled](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#asyncCredentialUpdateEnabled(java.lang.Boolean))` proprietà su on the builder: `true` ``` StsAssumeRoleCredentialsProvider provider = StsAssumeRoleCredentialsProvider.builder() .refreshRequest(r -> r .roleArn("arn:aws:iam::111122223333:role/example-role") .roleSessionName("example-session") .durationSeconds(3600)) // 1 hour session .staleTime(Duration.ofMinutes(5)) // Consider stale 5 minutes before expiration .prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration .asyncCredentialUpdateEnabled(true) // Refresh in background .build(); S3Client s3 = S3Client.builder() .credentialsProvider(provider) .build(); ``` Quando si richiama un'operazione on `s3Client` per la prima volta, un `[AssumeRoleRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/model/AssumeRoleRequest.html)` viene inviato a (STS). AWS Security Token Service STS restituisce credenziali temporanee valide per 15 minuti (900 secondi). L'`s3Client`istanza utilizza le credenziali memorizzate nella cache fino al momento di aggiornarle prima che trascorrano i 15 minuti. Per impostazione predefinita, l'SDK tenta di recuperare nuove credenziali per una nuova sessione tra 5 minuti e 1 minuto prima della scadenza della sessione corrente. La finestra di pre-fetch è configurabile utilizzando le proprietà and. `[prefetchTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#prefetchTime(java.time.Duration))` `[staleTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#staleTime(java.time.Duration))` È possibile configurare in modo analogo i seguenti provider di credenziali basati sulla sessione: + `StsWebIdentityTokenFileCredentialsProvider` + `StsGetSessionTokenCredentialsProvider` + `StsGetFederationTokenCredentialsProvider` + `StsAssumeRoleWithWebIdentityCredentialsProvider` + `StsAssumeRoleWithSamlCredentialsProvider` + `StsAssumeRoleCredentialsProvider` + `DefaultCredentialsProvider`(quando delega al provider di credenziali che utilizza le sessioni) + `ProcessCredentialsProvider` + `WebIdentityTokenFileCredentialsProvider` + `ContainerCredentialsProvider` + `InstanceProfileCredentialsProvider` Comprendere la memorizzazione nella cache delle credenziali consente di ottimizzare le prestazioni e l'affidabilità dell'applicazione quando si lavora con. Servizi AWS # Specificate un fornitore di credenziali specifico nel AWS SDK for Java 2.x Sebbene la catena di provider di credenziali predefinita sia utile per molti scenari, la specifica esplicita dei provider di credenziali offre un maggiore controllo sul comportamento di autenticazione, sulle prestazioni e sulla sicurezza. I motivi per cui potresti voler specificare un provider di credenziali potrebbero includere: + La catena di provider predefinita controlla più fonti in sequenza, il che può aggiungere latenza: ``` // The default provider chain checks might check multiple sources until it finds // sufficient configuration. S3Client s3Client = S3Client.builder().build(); // You can specify exactly where to look. S3Client optimizedClient = S3Client.builder() .credentialsProvider(InstanceProfileCredentialsProvider.create()) .build(); ``` + È necessario utilizzare posizioni non standard per accedere alla configurazione delle credenziali: ``` // Use configuration from a custom file location. S3Client s3Client = S3Client.builder() .credentialsProvider(ProfileCredentialsProvider.builder() .profileFile(ProfileFile.builder() .content(Paths.get("/custom/path/to/configuration/file")) .type(ProfileFile.Type.CONFIGURATION) // Expects all non-default profiles to be prefixed with "profile". .build()) .profileName("custom") .build()) .build(); ``` + Utilizza credenziali diverse per diversi client di servizio. Ad esempio, se l'applicazione deve accedere a più AWS account o utilizzare autorizzazioni diverse per servizi diversi: ``` // S3 client using one set of credentials. S3Client s3Client = S3Client.builder() .credentialsProvider(ProfileCredentialsProvider.create("s3-readonly")) .build(); // DynamoDB client using different credentials. DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .credentialsProvider(ProfileCredentialsProvider.create("dynamodb-admin")) .build(); ``` + Controlla il comportamento di aggiornamento delle credenziali: ``` // Create a provider with custom refresh behavior. StsAssumeRoleCredentialsProvider customRefreshProvider = StsAssumeRoleCredentialsProvider.builder() .refreshRequest(AssumeRoleRequest.builder() .roleArn("arn:aws:iam::123456789012:role/my-role") .roleSessionName("custom-session") .build()) .stsClient(StsClient.create()) .asyncCredentialUpdateEnabled(true) // Use a background thread to prefetch credentials. .build(); S3Client s3Client = S3Client.builder() .credentialsProvider(customRefreshProvider) .build(); ``` # Utilizza profili di configurazione AWS condivisi in AWS SDK for Java 2.x Utilizzando il `credentials` file condiviso`config`, puoi configurare diversi profili. Ciò consente all'applicazione di utilizzare più set di configurazione delle credenziali. Il `[default]` profilo è stato menzionato in precedenza. L'SDK utilizza la [ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html)classe per caricare le impostazioni dai profili definiti nel `credentials` file condiviso. Il seguente frammento di codice mostra come creare un client di servizio che utilizzi le impostazioni definite come parte del profilo denominato. `my_profile` ``` Region region = Region.US_WEST_2; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("my_profile")) .build(); ``` ## Imposta un profilo diverso come predefinito Per impostare un profilo diverso dal `[default]` profilo come predefinito per l'applicazione, imposta la variabile di `AWS_PROFILE` ambiente sul nome del profilo personalizzato. Per impostare questa variabile su Linux, macOS o Unix, usa: `export` ``` export AWS_PROFILE="other_profile" ``` Per impostare queste variabili su Windows, utilizza `set`: ``` set AWS_PROFILE="other_profile" ``` In alternativa, impostate la proprietà del sistema `aws.profile` Java sul nome del profilo. ## Ricarica le credenziali del profilo È possibile configurare qualsiasi provider di credenziali che disponga di un `profileFile()` metodo nel relativo generatore per ricaricare le credenziali del profilo. Queste classi di profilo di credenziali sono:,, e `ProfileCredentialsProvider` `DefaultCredentialsProvider` `InstanceProfileCredentialsProvider` `ProfileTokenProvider.` **Nota** Il ricaricamento delle credenziali del profilo funziona solo con le seguenti impostazioni nel file di profilo:`aws_access_key_id`,, `aws_secret_access_key` e. `aws_session_token` Impostazioni come`region`, `sso_session``sso_account_id`, e `source_profile` vengono ignorate. Per configurare un provider di credenziali supportato per ricaricare le impostazioni del profilo, fornisci un'istanza del metodo [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html)builder. `profileFile()` Il seguente esempio di codice mostra un `ProfileCredentialsProvider` che ricarica le impostazioni delle credenziali dal profilo. `[default]` ``` ProfileCredentialsProvider provider = ProfileCredentialsProvider .builder() .profileFile(ProfileFileSupplier.defaultSupplier()) .build(); // Set up a service client with the provider instance. DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .region(Region.US_EAST_1) .credentialsProvider(provider) .build(); /* Before dynamoDbClient makes a request, it reloads the credentials settings by calling provider.resolveCredentials(). */ ``` Quando `ProfileCredentialsProvider.resolveCredentials()` viene chiamato, l'SDK for Java ricarica le impostazioni. `ProfileFileSupplier.defaultSupplier()`è una delle [numerose implementazioni pratiche](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html) `ProfileFileSupplier` fornite dall'SDK. Se il tuo caso d'uso lo richiede, puoi fornire la tua implementazione. L'esempio seguente mostra l'uso del metodo di `ProfileFileSupplier.reloadWhenModified()` convenienza. `reloadWhenModified()`utilizza un `Path` parametro, che offre flessibilità nella designazione del file sorgente per la configurazione anziché la posizione standard `~/.aws/credentials` (o`config`). Le impostazioni verranno ricaricate quando `resolveCredentials()` viene chiamata solo se SDK determina che il contenuto del file è stato modificato. ``` Path credentialsFilePath = ... ProfileCredentialsProvider provider = ProfileCredentialsProvider .builder() .profileFile(ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS)) .profileName("my-profile") .build(); /* A service client configured with the provider instance calls provider.resolveCredential() before each request. */ ``` Il `ProfileFileSupplier.aggregate()` metodo unisce il contenuto di più file di configurazione. Siete voi a decidere se ricaricare un file per chiamata `resolveCredentials()` o se le impostazioni di un file vengono corrette al momento della prima lettura. L'esempio seguente mostra un file `DefaultCredentialsProvider` che unisce le impostazioni di due file che contengono le impostazioni del profilo. L'SDK ricarica le impostazioni nel file a cui fa riferimento la `credentialsFilePath` variabile ogni volta che `resolveCredentials()` viene chiamata e le impostazioni vengono modificate. Le impostazioni dell'`profileFile`oggetto rimangono le stesse. ``` Path credentialsFilePath = ...; ProfileFile profileFile = ...; DefaultCredentialsProvider provider = DefaultCredentialsProvider .builder() .profileFile(ProfileFileSupplier.aggregate( ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS), ProfileFileSupplier.fixedProfileFile(profileFile))) .profileName("my-profile") .build(); /* A service client configured with the provider instance calls provider.resolveCredential() before each request. */ ``` # Caricate le credenziali da un processo esterno utilizzando il AWS SDK for Java 2.x **avvertimento** Di seguito viene descritto un metodo per ottenere credenziali temporanee da un processo esterno. Questo può essere potenzialmente pericoloso, quindi procedi con cautela. Ti consigliamo di utilizzare altri fornitori di credenziali, se possibile. Se utilizzi questa opzione, ti consigliamo di assicurarti che il `config` file sia il più protetto possibile utilizzando le migliori pratiche di sicurezza per il tuo sistema operativo. Assicurati che lo strumento per le credenziali personalizzate non scriva `StdErr` informazioni segrete su. SDKs e AWS CLI può acquisire e registrare tali informazioni, esponendole potenzialmente a utenti non autorizzati. Con l'SDK for Java 2.x, puoi acquisire credenziali temporanee da un processo esterno per casi d'uso personalizzati. Esistono due modi per configurare questa funzionalità. ## Usa l'`credential_process`impostazione Se disponi di un metodo che fornisce credenziali temporanee, puoi integrarlo aggiungendo l'`credential_process`impostazione come parte di una definizione di profilo nel `config` file. Il valore specificato deve utilizzare il percorso completo del file di comando. Se il percorso del file contiene spazi, è necessario racchiuderlo tra virgolette. L'SDK chiama il comando esattamente come indicato e quindi legge i dati JSON da. `stdout` Gli esempi seguenti mostrano l'uso di questa impostazione per percorsi di file senza spazi e percorsi di file con spazi. ------ #### [ Linux/macOS ] **Nessuno spazio nel percorso del file** ``` [profile process-credential-profile] credential_process = /path/to/credential/file/credential_file.sh --custom-command custom_parameter ``` **Spazi nel percorso del file** ``` [profile process-credential-profile] credential_process = "/path/with/space to/credential/file/credential_file.sh" --custom-command custom_parameter ``` ------ #### [ Windows ] **Nessuno spazio nel percorso del file** ``` [profile process-credential-profile] credential_process = C:\Path\To\credentials.cmd --custom_command custom_parameter ``` **Spazi nel percorso del file** ``` [profile process-credential-profile] credential_process = "C:\Path\With Space To\credentials.cmd" --custom_command custom_parameter ``` ------ Il seguente frammento di codice mostra come creare un client di servizio che utilizza le credenziali temporanee definite come parte del profilo denominato. `process-credential-profile` ``` Region region = Region.US_WEST_2; S3Client s3Client = S3Client.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile")) .build(); ``` Per informazioni dettagliate sull'utilizzo di un processo esterno come fonte di credenziali temporanee, consultate la [sezione relativa alle credenziali di processo nella and Tools Reference](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html) Guide. AWS SDKs ## Utilizzate un `ProcessCredentialsProvider` In alternativa all'utilizzo delle impostazioni nel `config` file, puoi utilizzare gli SDK `[ProcessCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProcessCredentialsProvider.html)` per caricare le credenziali temporanee utilizzando Java. Gli esempi seguenti mostrano varie versioni di come specificare un processo esterno utilizzando `ProcessCredentialsProvider` e configurare un client di servizio che utilizza le credenziali temporanee. ------ #### [ Linux/macOS ] **Nessuno spazio nel percorso del file** ``` ProcessCredentialsProvider credentials = ProcessCredentialsProvider .builder() .command("/path/to/credentials.sh optional_param1 optional_param2") .build(); S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .credentialsProvider(credentials) .build(); ``` **Spazi nel percorso del file** ``` ProcessCredentialsProvider credentials = ProcessCredentialsProvider .builder() .command("/path\\ with\\ spaces\\ to/credentials.sh optional_param1 optional_param2") .build(); S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .credentialsProvider(credentials) .build(); ``` ------ #### [ Windows ] **Nessuno spazio nel percorso del file** ``` ProcessCredentialsProvider credentials = ProcessCredentialsProvider .builder() .command("C:\\Path\\To\\credentials.exe optional_param1 optional_param2") .build(); S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .credentialsProvider(credentials) .build(); ``` **Spazi nel percorso del file** ``` ProcessCredentialsProvider credentials = ProcessCredentialsProvider .builder() .command("\"C:\\Path\\With Spaces To\\credentials.exe\" optional_param1 optional_param2") .build(); S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .credentialsProvider(credentials) .build(); ``` ------ ## Usa IAM Roles Anywhere per l'autenticazione [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) Servizio AWS ti consente di ottenere AWS credenziali temporanee per carichi di lavoro eseguiti al di fuori di. AWS Consente l'accesso sicuro alle AWS risorse da ambienti locali o altri ambienti cloud. Prima di poter autenticare le richieste con IAM Roles Anywhere, devi prima raccogliere le informazioni richieste e scaricare lo strumento di supporto alle [credenziali](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html). Seguendo le istruzioni [introduttive](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html) nella Guida per l'utente di IAM Roles Anywhere, puoi creare gli elementi necessari. L'SDK for Java non dispone di un provider di credenziali dedicato per recuperare credenziali temporanee da IAM Roles Anywhere, ma puoi utilizzare lo strumento di supporto delle credenziali insieme a una delle opzioni per recuperare le credenziali [da](#credentials-process) un processo esterno. ### Usa l'impostazione in un profilo `credential_process` Il seguente frammento del file di AWS configurazione condiviso mostra un profilo denominato `roles_anywhere` che utilizza l'impostazione: `credential_process` ``` [profile roles_anywhere] credential_process = ./aws_signing_helper credential-process \ --certificate /path/to/certificate \ --private-key /path/to/private-key \ --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \ --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \ --role-arn arn:aws:iam::account:role/role-name-with-path ``` È necessario sostituire il testo mostrato in rosso con i valori dopo aver assemblato tutti gli artefatti. Il primo elemento dell'impostazione,`aws_signing_helper`, è l'eseguibile dello strumento di supporto alle credenziali ed `credential-process` è il comando. Quando configuri un client di servizio per l'utilizzo del `roles_anywhere` profilo, come illustrato nel codice seguente, l'SDK memorizza nella cache le credenziali temporanee e le aggiorna prima della scadenza: ``` S3Client s3Client = S3Client.builder() .credentialsProvider(ProfileCredentialsProvider.builder() .profileName("roles_anywhere").build()) .build(); ``` ### Configura un `ProcessCredentialsProvider` Come illustrato di seguito, puoi utilizzare un approccio basato solo sul codice con, `ProcessCredentialsProvider` anziché utilizzare le impostazioni del profilo: ``` ProcessCredentialsProvider processCredentialsProvider = ProcessCredentialsProvider.builder() .command(""" ./aws_signing_helper credential-process \ --certificate /path/to/certificate \ --private-key /path/to/private-key \ --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \ --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \ --role-arn arn:aws:iam::account:role/role-name-with-path """).build(); S3Client s3Client = S3Client.builder() .credentialsProvider(processCredentialsProvider) .build(); ``` Sostituisci il testo mostrato in rosso con i tuoi valori dopo aver assemblato tutti gli artefatti. # Fornite le credenziali in codice utilizzando il AWS SDK for Java 2.x Se la catena di credenziali predefinita o un provider o una catena di fornitori specifici o personalizzati non funzionano per l'applicazione, puoi fornire credenziali temporanee direttamente nel codice. Queste possono essere [credenziali di ruolo IAM](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html) come [descritto sopra](credentials-temporary.md#credentials-temporary-from-portal) o credenziali temporanee recuperate da (). AWS Security Token Service AWS STS Se hai recuperato credenziali temporanee utilizzando AWS STS, forniscile a un Servizio AWS client come mostrato nel seguente esempio di codice. 1. Assumi un ruolo chiamando. `StsClient.assumeRole()` 1. Crea un [StaticCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/StaticCredentialsProvider.html)oggetto e forniscilo con l'`AwsSessionCredentials`oggetto. 1. Configura il service client builder con `StaticCredentialsProvider` e crea il client. L'esempio seguente crea un client di servizio Amazon S3 utilizzando credenziali temporanee restituite da AWS STS per un ruolo assunto da IAM. ``` // The AWS IAM Identity Center identity (user) who executes this method does not have permission to list buckets. // The identity is configured in the [default] profile. public static void assumeRole(String roleArn, String roleSessionName) { // The IAM role represented by the 'roleArn' parameter can be assumed by identities in two different accounts // and the role permits the user to only list buckets. // The SDK's default credentials provider chain will find the single sign-on settings in the [default] profile. // The identity configured with the [default] profile needs permission to call AssumeRole on the STS service. try { Credentials tempRoleCredentials; try (StsClient stsClient = StsClient.create()) { AssumeRoleRequest roleRequest = AssumeRoleRequest.builder() .roleArn(roleArn) .roleSessionName(roleSessionName) .build(); AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest); tempRoleCredentials = roleResponse.credentials(); } // Use the following temporary credential items for the S3 client. String key = tempRoleCredentials.accessKeyId(); String secKey = tempRoleCredentials.secretAccessKey(); String secToken = tempRoleCredentials.sessionToken(); // List all buckets in the account associated with the assumed role // by using the temporary credentials retrieved by invoking stsClient.assumeRole(). StaticCredentialsProvider staticCredentialsProvider = StaticCredentialsProvider.create( AwsSessionCredentials.create(key, secKey, secToken)); try (S3Client s3 = S3Client.builder() .credentialsProvider(staticCredentialsProvider) .build()) { List buckets = s3.listBuckets().buckets(); for (Bucket bucket : buckets) { System.out.println("bucket name: " + bucket.name()); } } } catch (StsException | S3Exception e) { logger.error(e.getMessage()); System.exit(1); } } ``` ## Set di autorizzazioni Il seguente set di autorizzazioni definito in AWS IAM Identity Center consente all'identità (utente) di eseguire le due operazioni seguenti 1. Il `GetObject` funzionamento di Amazon Simple Storage Service. 1. Il `AssumeRole` funzionamento di AWS Security Token Service. Senza assumere il ruolo, il `s3.listBuckets()` metodo illustrato nell'esempio fallirebbe. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "sts:AssumeRole" ], "Resource": [ "*" ] } ] } ``` ------ ## Ruolo assunto ### Politica sulle autorizzazioni relative ai ruoli assunti La seguente politica di autorizzazioni è allegata al ruolo assunto nell'esempio precedente. Questa politica di autorizzazioni consente di elencare tutti i bucket nello stesso account del ruolo. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListAllMyBuckets" ], "Resource": [ "*" ] } ] } ``` ------ ### Politica di fiducia per i ruoli assunti La seguente politica di fiducia è associata al ruolo assunto nell'esempio precedente. La politica consente alle identità (utenti) di assumere il ruolo in due account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root", "arn:aws:iam::555555555555:root" ] }, "Action": "sts:AssumeRole", "Condition": {} } ] } ``` ------ # Leggi le credenziali del ruolo IAM su Amazon EC2 utilizzando l'SDK for Java 2.x Puoi utilizzare un ruolo IAM per gestire le credenziali temporanee per le applicazioni in esecuzione su un'istanza EC2 e che AWS CLI effettuano richieste API. AWS Ciò è preferibile all’archiviazione delle chiavi di accesso nell’istanza EC2. Per assegnare un AWS ruolo a un'istanza EC2 e renderlo disponibile per tutte le sue applicazioni, crei un profilo di istanza collegato all'istanza. Un profilo dell’istanza contiene il ruolo e consente ai programmi in esecuzione sull’istanza EC2 di ottenere le credenziali temporanee. Per ulteriori informazioni, consulta [Utilizzare un ruolo IAM per concedere autorizzazioni alle applicazioni che eseguono istanze Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) nella *Guida per l'utente IAM*. Questo argomento fornisce informazioni su come configurare l'applicazione Java per l'esecuzione su un'istanza EC2 e abilitare l'acquisizione IAM delle credenziali AWS SDK for Java 2.x di ruolo. ## Acquisisci le credenziali del ruolo IAM dall'ambiente Se l'applicazione crea un client di AWS servizio utilizzando il `create` metodo (o i `builder().build()` metodi), l'SDK for Java utilizza *la catena di provider di credenziali predefinita*. La catena di fornitori di credenziali predefinita cerca nell'ambiente di esecuzione gli elementi di configurazione che l'SDK può scambiare con credenziali temporanee. La [Catena di fornitori di credenziali predefinita in AWS SDK for Java 2.x](credentials-chain.md) sezione descrive il processo di ricerca completo. L'ultimo passaggio della catena di provider predefinita è disponibile solo quando l'applicazione viene eseguita su un' Amazon EC2 istanza. In questa fase, l'SDK utilizza un `InstanceProfileCredentialsProvider` per leggere il ruolo IAM definito nel profilo dell'istanza EC2. L'SDK acquisisce quindi le credenziali temporanee per quel ruolo IAM. Sebbene queste credenziali siano temporanee e alla fine scadano, An le aggiorna `InstanceProfileCredentialsProvider` periodicamente in modo che continuino a consentirne l'accesso. AWS ## Acquisisci le credenziali del ruolo IAM a livello di codice In alternativa alla catena di provider di credenziali predefinita che alla fine utilizza un client di servizio `InstanceProfileCredentialsProvider` su EC2, puoi configurare un client di servizio in modo esplicito con un. `InstanceProfileCredentialsProvider` Questo approccio è illustrato nel frammento seguente. ``` S3Client s3 = S3Client.builder() .credentialsProvider(InstanceProfileCredentialsProvider.create()) .build(); ``` ## Acquisisci in modo sicuro le credenziali dei ruoli IAM Per impostazione predefinita, le istanze EC2 eseguono [IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) (Instance Metadata Service) che consente agli SDK di accedere `InstanceProfileCredentialsProvider` a informazioni come il ruolo IAM che è stato configurato. Per impostazione predefinita, le istanze EC2 eseguono due versioni di IMDS: + Instance Metadata Service Version 1 ()IMDSv1: un metodo request/response + Instance Metadata Service Version 2 (IMDSv2): un metodo orientato alla sessione [IMDSv2 è un approccio più sicuro di.](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/) IMDSv1 Per impostazione predefinita, Java SDK tenta innanzitutto di IMDSv2 ottenere il ruolo IAM, ma se fallisce, ci prova IMDSv1. Tuttavia, poiché IMDSv1 è meno sicuro, AWS consiglia di utilizzare IMDSv2 solo l'SDK e di disabilitarne i tentativi. IMDSv1 Per utilizzare un approccio più sicuro, disabilita l'utilizzo dell'SDK IMDSv1 fornendo una delle seguenti impostazioni con un valore di. `true` + Variabile d'ambiente: `AWS_EC2_METADATA_V1_DISABLED` + Proprietà del sistema JVM: aws. `disableEc2MetadataV1` + Impostazione del file di configurazione condiviso: `ec2_metadata_v1_disabled` Con una di queste impostazioni impostata su`true`, l'SDK non carica le credenziali del ruolo IMDS utilizzando IMDSv1 se la chiamata iniziale fallisce. IMDSv2 # Configurare il comportamento dei tentativi in AWS SDK for Java 2.x Le chiamate a Servizi AWS possono fallire occasionalmente per motivi imprevisti. Alcuni errori, come la limitazione (frequenza superata) o gli errori transitori, potrebbero avere esito positivo se la chiamata viene ritentata. AWS SDK for Java 2.x Dispone di un meccanismo integrato per rilevare tali errori e riprovare automaticamente la chiamata, abilitato di default per tutti i client. Questa pagina descrive come funziona, come configurare le diverse modalità e personalizzare il comportamento dei tentativi. ## Strategie di nuovo tentativo Una strategia di ripetizione dei tentativi è un meccanismo utilizzato nell'SDK per implementare nuovi tentativi. Ogni client SDK dispone di una strategia di riprova creata in fase di compilazione che non può essere modificata dopo la creazione del client. La strategia di riprova ha le seguenti responsabilità. + Classificate le eccezioni come riprovabili o meno. + Calcola il ritardo suggerito per attendere prima del tentativo successivo. + Mantieni un [token bucket](https://en.wikipedia.org/wiki/Token_bucket) che fornisca un meccanismo per bloccare i nuovi tentativi quando una grande percentuale di richieste ha esito negativo e i nuovi tentativi non hanno esito positivo. **Nota** *Prima del rilascio delle *strategie* di riprova con la versione 2.26.0 dell'SDK, le politiche di riprova fornivano il meccanismo di riprova dell'SDK.* *L'API retry *policy* è costituita dalla [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryPolicy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryPolicy.html)classe principale del `software.amazon.awssdk.core.retry` pacchetto, mentre il pacchetto contiene gli elementi dell'API retry strategy. `[software.amazon.awssdk.retries](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/package-summary.html)`* L'API retry strategy è stata introdotta come parte dell' AWS ampio sforzo volto a unificare le interfacce e il comportamento dei componenti principali di. SDKs L'SDK for Java 2.x include tre strategie di riprova integrate: standard, legacy e adattiva. Tutte e tre le strategie di riprova sono preconfigurate per riprovare una serie di eccezioni riprovabili. Esempi di errori riutilizzabili sono i timeout dei socket, la limitazione sul lato del servizio, gli errori di blocco simultanei o ottimistici e gli errori temporanei del servizio. ### Strategia di riprova standard La [strategia di riprova standard](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.html) è l'`RetryStrategy`implementazione consigliata per i normali casi d'uso. A differenza della`AdaptiveRetryStrategy`, la strategia standard è generalmente utile in tutti i casi d'uso con nuovi tentativi. Per impostazione predefinita, la strategia di ripetizione standard esegue le seguenti operazioni. + Riprova in base alle condizioni configurate in fase di compilazione. Puoi regolarlo con`[StandardRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.Builder.html)#retryOnException`. + Riprova 2 volte per un totale di 3 tentativi. Puoi regolarlo con`StandardRetryStrategy.Builder#maxAttempts(int)`. + Per le eccezioni che non prevedono il throttling, utilizza la strategia di `[BackoffStrategy](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)#exponentialDelay` backoff, con un ritardo base di 100 millisecondi e un ritardo massimo di 20 secondi. Puoi `StandardRetryStrategy.Builder#backoffStrategy` regolarlo con. + Per le eccezioni relative al throttling, utilizza la strategia di `BackoffStrategy#exponentialDelay` backoff, con un ritardo base di 1 secondo e un ritardo massimo di 20 secondi. Puoi regolarlo con. `StandardRetryStrategy.Builder#throttlingBackoffStrategy` + Interrompe il circuito (disabilita i nuovi tentativi) in caso di gravi guasti a valle. Il primo tentativo viene sempre eseguito, solo i nuovi tentativi sono disabilitati. Regola con`StandardRetryStrategy.Builder#circuitBreakerEnabled`. ### Strategia preesistente di nuovi tentativi La [precedente strategia di ripetizione](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.html) dei tentativi è `RetryStrategy` destinata ai casi d'uso normali, tuttavia è obsoleta a favore di. `StandardRetryStrategy` Questa è la strategia di riprova predefinita utilizzata dai clienti quando non si specifica un'altra strategia. È caratterizzata dal fatto che le eccezioni di throttling e non throttling vengono trattate in modo diverso, per le eccezioni di throttling il ritardo di base per il backoff è maggiore (500 ms) rispetto al ritardo di base per le eccezioni senza limitazione (100 ms) e le eccezioni di throttling non influiscono sullo stato del token bucket. L'esperienza nell'uso di questa strategia su larga scala ha dimostrato che non è particolarmente migliore della strategia di riprova standard. AWS Inoltre, non riesce a proteggere i servizi a valle dalle tempeste di tentativi ripetuti e può portare alla carenza di risorse da parte del client. Per impostazione predefinita, la strategia di ripetizione dei tentativi precedente esegue le seguenti operazioni. + Riprova in base alle condizioni configurate in fase di compilazione. Puoi regolarlo con`[LegacyRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.Builder.html)#retryOnException`. + Riprova 3 volte per un totale di 4 tentativi. Puoi regolarlo con`LegacyRetryStrategy.Builder#maxAttempts(int)`. + Per le eccezioni che non prevedono il throttling, utilizza la strategia di `BackoffStrategy#exponentialDelay` backoff, con un ritardo base di 100 millisecondi e un ritardo massimo di 20 secondi. Puoi regolarlo con `LegacyRetryStrategy.Builder#backoffStrategy.` + Per le eccezioni di limitazione, utilizza la strategia di `BackoffStrategy#exponentialDelay` backoff, con un ritardo base di 500 millisecondi e un ritardo massimo di 20 secondi. Puoi regolarlo `LegacyRetryStrategy.Builder#throttlingBackoffStrategy` con. + Interrompe il circuito (disabilita i nuovi tentativi) in caso di gravi guasti a valle. L'interruzione del circuito non impedisce mai il successo del primo tentativo. È possibile modificare questo comportamento con`LegacyRetryStrategy.Builder#circuitBreakerEnabled`. + Lo stato dell'interruttore automatico non è influenzato dalle eccezioni di limitazione. ### Strategia adattiva di nuovi tentativi La [strategia adattiva di riprova](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.html) è `RetryStrategy` adatta ai casi d'uso con un elevato livello di vincoli di risorse. La strategia adattiva di riprova include tutte le funzionalità della strategia standard e aggiunge un limitatore di velocità sul lato client che misura la frequenza delle richieste limitate rispetto alle richieste non limitate. La strategia utilizza questa misurazione per rallentare le richieste nel tentativo di rimanere entro una larghezza di banda sicura, causando idealmente zero errori di limitazione. Per impostazione predefinita, la strategia di ripetizione adattiva esegue le seguenti operazioni. + Riprova in base alle condizioni configurate in fase di compilazione. Puoi regolarlo con`[AdaptiveRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.Builder.html)#retryOnException`. + Riprova 2 volte per un totale di 3 tentativi. Puoi regolarlo con`AdaptiveRetryStrategy.Builder#maxAttempts(int)`. + Utilizza un ritardo di backoff dinamico basato sul carico corrente rispetto alla risorsa a valle. + Effettua l'interruzione del circuito (disabilitando i nuovi tentativi) in caso di un numero elevato di guasti a valle. L'interruzione del circuito può impedire un secondo tentativo in scenari di interruzione per proteggere il servizio a valle. **avvertimento** La strategia di ripetizione adattiva presuppone che il client lavori su una singola risorsa (ad esempio, una tabella DynamoDB o un bucket Amazon S3). Se si utilizza un singolo client per più risorse, le limitazioni o le interruzioni associate a una risorsa determinano un aumento della latenza e degli errori quando il client accede a tutte le altre risorse. Quando utilizzi la strategia di ripetizione adattiva, ti consigliamo di utilizzare un singolo client per ogni risorsa. Si consiglia inoltre di utilizzare questa strategia in situazioni in cui tutti i client utilizzano la strategia adattiva di ripetizione dei tentativi rispetto alla risorsa. **Importante** Il rilascio delle strategie di ripetizione con la versione 2.26.0 di Java SDK include il nuovo valore di enumerazione. [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html#ADAPTIVE_V2](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html#ADAPTIVE_V2) La `ADAPTIVE_V2` modalità corregge un errore che non è riuscito a ritardare il primo tentativo quando in precedenza erano stati rilevati errori di limitazione. Con la versione 2.26.0, gli utenti ottengono automaticamente il comportamento della `ADAPTIVE_V2` modalità impostando la modalità come `adaptive` con una variabile di ambiente, una proprietà di sistema o un'impostazione del profilo. Non esiste alcun `adaptive_v2` valore per queste impostazioni. Per informazioni su come impostare la modalità, vedere la [Specificare una strategia](#retry-strategies-specify) sezione seguente. Gli utenti possono ottenere il comportamento precedente impostando la modalità nel codice utilizzando`RetryMode.ADAPTIVE`. ### Riepilogo: confronto dei valori predefiniti della strategia Retry La tabella seguente mostra i valori predefiniti per le proprietà di ogni strategia di nuovo tentativo. | Strategia | Numero massimo di tentativi | Ritardo di base per errori che non riguardano la limitazione | Ritardo di base per errori di limitazione | Dimensioni del bucket token | Costo del token per ogni nuovo tentativo senza limitazione | Costo del token per ogni nuovo tentativo di limitazione | | --- | --- | --- | --- | --- | --- | --- | | Standard | 3 | 100 ms | 1000 ms | 500 | 5 | 5 | | Legacy | 4 | 100 ms | 500 ms | 500 | 5 | 0 | | Adattabile | 3 | 100 ms | 100 ms | 500 | 5 | 5 | **Nota** I client DynamoDB utilizzano un numero massimo di tentativi predefinito di 8 per tutte le strategie di ripetizione, che è superiore ai valori mostrati nella tabella precedente per gli altri client. Servizio AWS ## Specificare una strategia Avete quattro modi per specificare una strategia per il vostro cliente di assistenza. ### In codice Quando crei un client, puoi configurare un'espressione lambda con una strategia di riprova. Il seguente frammento configura una strategia di riprova standard che utilizza valori predefiniti su un client di servizio DynamoDB. ``` DynamoDbClient client = DynamoDbClient.builder() .overrideConfiguration(o -> o.retryStrategy(RetryMode.STANDARD)) .build(); ``` È possibile specificare o al posto di. `RetryMode.LEGACY` `RetryMode.ADAPTIVE` `RetryMode.STANDARD` ### Come impostazione del profilo Includi `retry_mode` come impostazione del profilo nel [file di AWS configurazione condiviso](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). `legacy`Specificare `standard` o `adaptive` come valore. Se impostata come impostazione del profilo, tutti i client di servizio creati mentre il profilo è attivo utilizzano la strategia di ripetizione dei tentativi specificata con valori predefiniti. È possibile ignorare questa impostazione configurando una strategia di nuovo tentativo nel codice, come mostrato in precedenza. Con il seguente profilo, tutti i client di servizio utilizzano la strategia di riprova standard. ``` [profile dev] region = us-east-2 retry_mode = standard ``` ### Come proprietà del sistema JVM È possibile configurare una strategia di riprova per tutti i client di servizio, a meno che non sia sovrascritta nel codice, utilizzando la proprietà di sistema. `aws.retryMode` Specificare `standard` o come `legacy` valore. `adaptive` Utilizzate lo `-D` switch quando richiamate Java, come illustrato nel comando seguente. ``` java -Daws.retryMode=standard ... ``` In alternativa, impostate la proprietà di sistema nel codice *prima di* creare qualsiasi client, come mostrato nel frammento seguente. ``` public void main(String[] args) { // Set the property BEFORE any AWS service clients are created. System.setProperty("aws.retryMode", "standard"); ... } ``` ### Con una variabile di ambiente È inoltre possibile utilizzare la variabile di `AWS_RETRY_MODE` ambiente con un valore di `standard``legacy`, o`adaptive`. Analogamente all'impostazione del profilo o alla proprietà del sistema JVM, la variabile di ambiente configura tutti i client di servizio con la modalità di riprova specificata, a meno che non si configuri un client nel codice. Il comando seguente imposta la modalità retry `standard` per la sessione di shell corrente. ``` export AWS_RETRY_MODE=standard ``` ## Personalizza una strategia Puoi personalizzare qualsiasi strategia di nuovo tentativo impostando il numero massimo di tentativi, la strategia di backoff e le eccezioni che possono essere riprovate. È possibile personalizzare quando si crea una strategia di ripetizione dei tentativi o quando si crea un client utilizzando un generatore di override che consente ulteriori perfezionamenti della strategia configurata. ### Personalizza il numero massimo di tentativi È possibile configurare il numero massimo di tentativi durante la costruzione del client, come illustrato nella seguente dichiarazione. L'istruzione seguente personalizza la strategia di ripetizione dei tentativi predefinita per il client fino a un massimo di 5 tentativi, un primo tentativo più 4 tentativi. ``` DynamoDbClient client = DynamoDbClient.builder() .overrideConfiguration(o -> o.retryStrategy(b -> b.maxAttempts(5))) .build(); ``` In alternativa, è possibile creare la strategia e fornirla al client come illustrato nel seguente esempio di codice. Il codice seguente sostituisce i 3 tentativi massimi standard con 10 e configura un client DynamoDB con la strategia personalizzata. ``` StandardRetryStrategy strategy = AwsRetryStrategy.standardRetryStrategy() .toBuilder() .maxAttempts(10) .build(); DynamoDbClient client = DynamoDbClient.builder() .overrideConfiguration(o -> o.retryStrategy(strategy)) .build(); ``` **avvertimento** Si consiglia di configurare ogni client con un'istanza unica. `RetryStrategy` Se un'`RetryStrategy`istanza è condivisa, gli errori in un client potrebbero influire sul comportamento dei tentativi nell'altro. È inoltre possibile impostare il numero massimo di tentativi per tutti i client utilizzando [impostazioni esterne](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) anziché codice. È possibile configurare questa impostazione come descritto nella [Specificare una strategia](#retry-strategies-specify) sezione. ### Personalizza le eccezioni riprovabili È possibile configurare eccezioni aggiuntive che attivano nuovi tentativi durante la creazione del client. Questa personalizzazione viene fornita per i casi limite in cui vengono generate eccezioni che non sono incluse nel set predefinito di eccezioni riutilizzabili. I `retryOnExceptionOrCause` metodi `retryOnException` and **aggiungono** nuovi tipi di eccezione al set esistente di eccezioni riutilizzabili; non sostituiscono il set predefinito. Ciò consente di estendere il comportamento dei tentativi mantenendo le funzionalità di ripetizione predefinite dell'SDK. Il `retryOnExceptionOrCause` metodo aggiunge un'eccezione riutilizzabile se l'SDK genera l'eccezione diretta o se l'eccezione viene inserita come causa in un'altra eccezione. Il seguente frammento di codice mostra i metodi utilizzati per personalizzare le eccezioni relative ai tentativi: e. `retryOnException` `retryOnExceptionOrCause` I `retryOnExceptionOrCause` metodi aggiungono un'eccezione riutilizzabile se l'SDK genera l'eccezione diretta o se l'eccezione è inclusa. ``` DynamoDbClient client = DynamoDbClient.builder() .overrideConfiguration(o -> o.retryStrategy( b -> b.retryOnException(EdgeCaseException.class) .retryOnExceptionOrCause(WrappedEdgeCaseException.class))) .build(); ``` **Importante** I nuovi tentativi sono disabilitati per il client asincrono Kinesis quando si chiama [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html#subscribeToShard(software.amazon.awssdk.services.kinesis.model.SubscribeToShardRequest,software.amazon.awssdk.services.kinesis.model.SubscribeToShardResponseHandler)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html#subscribeToShard(software.amazon.awssdk.services.kinesis.model.SubscribeToShardRequest,software.amazon.awssdk.services.kinesis.model.SubscribeToShardResponseHandler))un metodo, indipendentemente dalla configurazione della strategia di ripetizione. ### Personalizza la strategia di backoff È possibile creare la strategia di backoff e fornirla al cliente. Il codice seguente ne crea una `BackoffStrategy` che sostituisce la strategia di backoff esponenziale con ritardo esponenziale predefinita della strategia standard. ``` BackoffStrategy backoffStrategy = BackoffStrategy.exponentialDelay(Duration.ofMillis(150), // The base delay. Duration.ofSeconds(15)); // The maximum delay. DynamoDbClient client = DynamoDbClient.builder() .overrideConfiguration(o -> o.retryStrategy( b -> b.backoffStrategy(backoffStrategy))) .build(); ``` ## Migrazione da `RetryPolicy` a `RetryStrategy` `RetryPolicy`(l'API retry policy) sarà supportata per il prossimo futuro. Se attualmente utilizzi un'istanza di `RetryPolicy` per configurare il tuo client, tutto funzionerà come prima. Dietro le quinte, Java SDK lo adatta a un. `RetryStrategy` Le nuove interfacce retry strategy offrono le stesse funzionalità di un `RetryPolicy` ma vengono create e configurate in modo diverso. # Configura i timeout in AWS SDK for Java 2.x AWS SDK for Java 2.x Fornisce più livelli di configurazione del timeout per aiutarti a creare applicazioni resilienti. L'SDK offre diversi tipi di timeout che interagiscono per ottimizzare le prestazioni e l'affidabilità dell'applicazione. Esistono due categorie principali di timeout nell'SDK: + **Service Client Timeout: timeout** di alto livello che controllano le operazioni delle API + **Timeout del client HTTP: timeout di basso livello che controllano le comunicazioni di rete** ## Timeout del client di servizio I timeout dei client di servizio operano a livello di API e controllano il comportamento generale delle operazioni di servizio, inclusi nuovi tentativi e tentativi multipli. ### Timeout delle chiamate API Il timeout della chiamata API imposta la quantità di tempo massima per un'intera operazione API, inclusi tutti i tentativi di nuovo tentativo. Questo timeout fornisce un limite rigido al tempo di attesa dell'applicazione per il completamento di un'operazione. ``` S3Client s3Client = S3Client.builder() .overrideConfiguration(ClientOverrideConfiguration.builder() .apiCallTimeout(Duration.ofMinutes(2)) // Total time for entire operation, such as when you call the getObject method. .build()) .build(); ``` Caratteristiche principali: + Include tutti i tentativi di riprova. + Include il tempo di attesa tra un tentativo e l'altro. + Fornisce il tempo di attesa massimo assoluto. + Impedisce l'esecuzione indefinita delle operazioni. ### Timeout del tentativo di chiamata API Il timeout del tentativo di chiamata API imposta il tempo massimo per un singolo tentativo di operazione API. Se questo timeout viene superato, l'SDK riprova l'operazione (se i tentativi sono configurati) anziché fallire l'intera chiamata. ``` S3Client s3Client = S3Client.builder() .overrideConfiguration(ClientOverrideConfiguration.builder() .apiCallAttemptTimeout(Duration.ofSeconds(30)) // Time for single attempt. .build()) .build(); ``` Caratteristiche principali: + Si applica solo ai tentativi individuali. + Consente errori e ritentativi rapidi in caso di richieste lente. + Deve essere inferiore al timeout della chiamata API. + Aiuta a identificare e risolvere problemi transitori. ### Configura i timeout dei client di servizio Puoi configurare i timeout dei client di servizio a livello globale per tutte le operazioni o per richiesta: **Configurazione globale:** ``` S3Client s3Client = S3Client.builder() .overrideConfiguration(b -> b .apiCallTimeout(Duration.ofSeconds(105L)) .apiCallAttemptTimeout(Duration.ofSeconds(25L))) .build(); // When you use the s3Client for an API operation, the SDK uses the configured timeout values. ``` **Configurazione per richiesta:** ``` S3Client basicS3Client = S3Client.create(); // The following configuration uses the same settings as shown before, but these settings // apply to only the `putObject` call. When you use `basicS3Client` in another API call without // supplying the override configuration, there are no API timeout limits. No timeout limits is the default for the SDK. AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder() .apiCallTimeout(Duration.ofSeconds(105L)) .apiCallAttemptTimeout(Duration.ofSeconds(25L)) .build(); basicS3Client.putObject(b -> b .bucket("amzn-s3-demo-bucket") .key("example-key") .overrideConfiguration(overrideConfiguration), RequestBody.fromString("test")); ``` ### Migliori pratiche per i timeout delle API Per impostazione predefinita, l'SDK for Java 2.x non imposta i timeout delle chiamate API o i timeout dei singoli tentativi di chiamata API. Imposta i timeout sia per i singoli tentativi che per l'intera richiesta. Questo aiuta l'applicazione a fallire rapidamente quando problemi temporanei fanno sì che i tentativi di richiesta richiedano più tempo o quando si verificano problemi irreversibili di rete. ## Timeout del client HTTP I timeout dei client HTTP operano a livello di rete e controllano vari aspetti della comunicazione HTTP. Questi timeout variano a seconda dell'implementazione del client HTTP utilizzata. ### Timeout di connessione Il timeout della connessione controlla il tempo di attesa quando si stabilisce una nuova connessione all'endpoint. Servizio AWS ``` // Available with all HTTP clients. ApacheHttpClient.builder() .connectionTimeout(Duration.ofSeconds(5L)) .build(); ``` Scopo: + Evita il blocco dei problemi di connettività di rete. + Si guasta rapidamente quando i servizi non sono raggiungibili. + Essenziale per le applicazioni che richiedono una gestione tempestiva degli errori. ### Socket Timeout (Apache e client) URLConnection Il timeout del socket controlla per quanto tempo attendere i dati su una connessione stabilita. ``` ApacheHttpClient.builder() .socketTimeout(Duration.ofSeconds(30L)) // Time to wait for response data. .build(); ``` ### Timeout di lettura e scrittura (client Netty) Il client Netty fornisce timeout separati per le operazioni di lettura e scrittura: ``` NettyNioAsyncHttpClient.builder() .readTimeout(Duration.ofSeconds(30L)) // Reading response data. .writeTimeout(Duration.ofSeconds(30L)) // Writing request data. .build(); ``` ### Timeout di negoziazione TLS (client Netty) Controlla il tempo consentito per la stretta di mano: TLS/SSL ``` NettyNioAsyncHttpClient.builder() .tlsNegotiationTimeout(Duration.ofSeconds(3L)) .build(); ``` ### Timeout del pool di connessioni Alcuni client HTTP forniscono timeout per le operazioni del pool di connessioni: ``` ApacheHttpClient.builder() .connectionAcquisitionTimeout(Duration.ofSeconds(10L)) // Wait for pool connection. .connectionTimeToLive(Duration.ofMinutes(5L)) // Maximum connection age. .connectionMaxIdleTime(Duration.ofSeconds(60L)) // Maximum idle time. .build() ``` [Configurare i client HTTP](http-configuration.md)contiene ulteriori informazioni sui client HTTP nel AWS SDK for Java 2.x ## Interazioni e gerarchia di timeout Comprendere come interagiscono i diversi timeout è fondamentale per una corretta configurazione: ### Gerarchia dei timeout ``` API Call Timeout (2 minutes) ├── Retry Attempt 1 │ ├── API Call Attempt Timeout (45 seconds) │ └── HTTP Client Timeouts │ ├── Connection Timeout (5 seconds) │ ├── TLS Negotiation Timeout (3 seconds) │ └── Read/Write Timeout (30 seconds) ├── Retry Attempt 2 │ └── [Same structure as Attempt 1] └── Retry Attempt 3 └── [Same structure as Attempt 1] ``` ### Regole di configurazione Timeout della chiamata API ≥ timeout del tentativo di chiamata API ``` // Correct configuration. .apiCallTimeout(Duration.ofMinutes(2)) // 120 seconds. .apiCallAttemptTimeout(Duration.ofSeconds(30)) // 30 seconds. ``` Timeout del tentativo di chiamata API ≥ timeout del client HTTP ``` // HTTP client timeouts must be less than attempt timeout. .apiCallAttemptTimeout(Duration.ofSeconds(30L)) // 30 seconds. // HTTP client configuration. .connectionTimeout(Duration.ofSeconds(5L)) // 5 seconds. .readTimeout(Duration.ofSeconds(25L)) // 25 seconds (< 30). ``` Tieni conto di più tentativi ``` // If you have 3 retry attempts, each taking up to 30 seconds // API call timeout must be at least 90 seconds plus overhead. .apiCallTimeout(Duration.ofMinutes(2L)) // 120 seconds. .apiCallAttemptTimeout(Duration.ofSeconds(30)) // 30 seconds per attempt. ``` ## Usa impostazioni di configurazione intelligenti predefinite L'SDK fornisce impostazioni predefinite intelligenti che configurano automaticamente i valori di timeout appropriati: ``` // Enable smart defaults. S3Client client = S3Client.builder() .defaultsMode(DefaultsMode.AUTO) // Automatically choose appropriate defaults. .build(); // Available modes: // - STANDARD: Balanced defaults // - IN_REGION: Optimized for same-region calls // - CROSS_REGION: Optimized for cross-region calls // - MOBILE: Optimized for mobile applications // - AUTO: Automatically detect and choose appropriate mode // - LEGACY: Provides settings that were used before smart defaults existed. ``` Le impostazioni predefinite intelligenti configurano automaticamente: + Valori di timeout della connessione. + Valori di timeout della negoziazione TLS. + Altre impostazioni del client. ## Riepilogo Una configurazione efficace del timeout AWS SDK for Java 2.x richiede la comprensione dell'interazione tra i timeout del client di servizio e i timeout del client HTTP: 1. I **timeout dei client di servizio controllano** il comportamento delle API di alto livello. 1. I **timeout dei client HTTP controllano il comportamento di rete di basso livello**. 1. **Una gerarchia adeguata** garantisce che i timeout funzionino insieme in modo efficace. 1. Le **impostazioni predefinite intelligenti** forniscono buoni punti di partenza per la maggior parte delle applicazioni. Configura i timeout in modo appropriato per il tuo caso d'uso per creare applicazioni che siano resilienti ai problemi di rete e reattive agli utenti. # Configurazione delle funzionalità di osservabilità in AWS SDK for Java 2.x La telemetria è la raccolta e la trasmissione automatizzate di dati da fonti remote che consentono di monitorare e analizzare il comportamento del sistema. L'osservabilità nell'SDK for Java 2.x offre agli sviluppatori una visione completa del modo in cui le loro applicazioni Java interagiscono Servizi AWS attraverso ricchi dati di telemetria che catturano l'intero ciclo di vita della richiesta. Queste funzionalità consentono di raccogliere, analizzare e visualizzare segnali di telemetria come metriche, log e tracce, consentendovi di monitorare i modelli di richiesta, identificare i punti deboli e ottimizzare le interazioni dell'applicazione per migliorare l'affidabilità e le prestazioni. AWS **Topics** + [Metriche](metrics.md) + [Monitoraggio](monitoring-overview.md) + [Registrazione dei log](logging-slf4j.md) # Pubblica le metriche SDK da AWS SDK for Java 2.x Con il AWS SDK for Java 2.x puoi raccogliere metriche sui client di servizio e sulle richieste nella tua applicazione, analizzare l'output in Amazon CloudWatch Logs e quindi agire di conseguenza. Per impostazione predefinita, la raccolta delle metriche è disabilitata nell'SDK. Questo argomento ti aiuta ad abilitarlo e configurarlo. ## Guida introduttiva alle metriche SDK Per abilitare la raccolta delle metriche nella tua applicazione, scegli l'implementazione appropriata dell'`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`interfaccia in base al tuo caso d'uso e segui le istruzioni di configurazione dettagliate: **Per applicazioni a lunga durata:** + Utilizzare `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` + Per istruzioni di configurazione complete, esempi di codice e opzioni di configurazione, consulta [Pubblicare metriche SDK da applicazioni a esecuzione prolungata](metric-pub-impl-cwmp.md). **Per le funzioni: AWS Lambda ** + Utilizzare `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` + Consulta [Publish SDK metrics for AWS Lambda functions per](metric-pub-impl-emf.md) istruzioni di configurazione complete, dipendenze e configurazioni specifiche per Lambda. **Per la risoluzione dei problemi e l'output della console:** + Utilizzare `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` + Consulta [Output SDK Metrics to console per lo sviluppo e il debug](metric-pub-impl-logging.md) per istruzioni di configurazione, opzioni di formattazione ed esempi per lo sviluppo locale e la risoluzione dei problemi. ## Anteprima rapida dell'implementazione Ecco come si presentano le metriche di abilitazione per ogni caso d'uso: **Applicazioni a lunga durata:** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Funzioni Lambda:** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **Sviluppo e debug:** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## Limitazione delle metriche del client S3 basato su CRT AWS Il [client S3 AWS basato su CRT attualmente](crt-based-s3-client.md) non supporta la raccolta di metriche SDK. Il builder per un'istanza client S3 AWS basata su CRT non fornisce metodi per configurare gli editori di [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html)metriche. ## Quando sono disponibili le metriche? Le metriche sono generalmente disponibili entro 5-10 minuti dall'emissione da parte dell'SDK for Java. Per informazioni accurate e up-to-date metriche, controlla Cloudwatch almeno 10 minuti dopo aver emesso le metriche delle tue applicazioni Java. ## Quali informazioni vengono raccolte? La raccolta di metriche include quanto segue: + Numero di richieste API, incluso l'esito positivo o negativo + Informazioni Servizi AWS sulla chiamata nelle richieste API, incluse le eccezioni restituite + La durata di varie operazioni come Marshalling, Signing e richieste HTTP + Metriche del client HTTP, come il numero di connessioni aperte, il numero di richieste in sospeso e il nome del client HTTP utilizzato **Nota** Le metriche disponibili variano in base al client HTTP. Per un elenco completo, consulta le [metriche del client di servizio](metrics-list.md). ## Come posso usare queste informazioni? Puoi utilizzare le metriche raccolte dall'SDK per monitorare i client di servizio nella tua applicazione. Puoi esaminare le tendenze generali di utilizzo, identificare anomalie, esaminare le eccezioni restituite dai client di servizio o approfondire per comprendere un problema particolare. Utilizzando Amazon CloudWatch Logs, puoi anche creare allarmi per avvisarti non appena l'applicazione raggiunge una condizione da te definita. [Per ulteriori informazioni, consulta [Using Amazon CloudWatch Logs Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) e Using [Amazon CloudWatch Logs Alarms nella Amazon Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) User Guide. CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) # Pubblica i parametri SDK di applicazioni a lunga esecuzione utilizzando il AWS SDK for Java 2.x Poiché l'`[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)`implementazione aggrega e carica periodicamente le metriche su Amazon CloudWatch con un certo ritardo, il suo utilizzo è più adatto per applicazioni a lunga durata. Le impostazioni predefinite dell'editore delle metriche hanno lo scopo di ridurre al minimo l'utilizzo e i CloudWatch costi della memoria, fornendo al contempo un'utile quantità di informazioni sui dati metrici. ## Configurazione Prima di poter abilitare e utilizzare le metriche utilizzando`CloudWatchMetricPublisher`, completa i seguenti passaggi. ### Passaggio 1: aggiungere la dipendenza richiesta Configura le dipendenze del progetto (ad esempio, nel tuo `build.gradle` file `pom.xml` o) per utilizzare la versione `2.14.0` o successiva di. AWS SDK per Java Includi l'`cloudwatch-metric-publisher`ArtifactID con il `2.14.0` numero di versione o successivo nelle dipendenze del progetto. Esempio: ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### Passaggio 2: configura le autorizzazioni richieste Abilita `cloudwatch:PutMetricData` le autorizzazioni per l'identità IAM utilizzata dall'editore delle metriche per consentire all'SDK for Java di scrivere metriche. ## Abilita le metriche per una richiesta specifica La classe seguente mostra come abilitare l'editore di CloudWatch metriche per una richiesta ad Amazon DynamoDB. Utilizza la configurazione predefinita di Metrics Publisher. ``` import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest; public class DefaultConfigForRequest { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.create(); // Publish metrics the for ListTables operation. ddb.listTables(ListTablesRequest.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build()); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` **Importante** Assicurati che l'applicazione richiami `close` l'`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`istanza quando il client del servizio non è più in uso. In caso contrario, potrebbero verificarsi fughe di thread o descrittori di file. ## Abilita le metriche di riepilogo per un client di servizio specifico Il seguente frammento di codice mostra come abilitare un editore di CloudWatch metriche con impostazioni predefinite per un client di servizio. ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## Personalizza un editore di metriche CloudWatch La seguente classe dimostra come impostare una configurazione personalizzata per l'editore delle metriche per uno specifico client di servizio. Le personalizzazioni includono il caricamento di un profilo specifico, la specificazione di una AWS regione in cui l'editore delle metriche invia le richieste e la personalizzazione della frequenza a cui l'editore invia le metriche. CloudWatch ``` import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.core.metrics.CoreMetric; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import java.time.Duration; public class CustomConfigForDDBClient { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder() .cloudWatchClient(CloudWatchAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(ProfileCredentialsProvider.create("cloudwatch")) .build()) .uploadFrequency(Duration.ofMinutes(5)) .maximumCallsPerUpload(100) .namespace("ExampleSDKV2Metrics") .detailedMetrics(CoreMetric.API_CALL_DURATION) .build(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); // Publish metrics for DynamoDB operations. ddb.listTables(); ddb.describeEndpoints(); ddb.describeLimits(); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` Le personalizzazioni mostrate nello snippet precedente hanno i seguenti effetti. + Il `cloudWatchClient` metodo consente di personalizzare il CloudWatch client utilizzato per inviare le metriche. In questo esempio, utilizziamo una regione diversa da quella predefinita di *us-east-1* in cui il client invia le metriche. Utilizziamo anche un profilo con nome diverso, *cloudwatch*, le cui credenziali verranno utilizzate per autenticare le richieste. CloudWatch Tali credenziali devono avere le autorizzazioni per. `cloudwatch:PutMetricData` + Il `uploadFrequency` metodo consente di specificare la frequenza con cui l'editore di metriche carica le metriche. CloudWatch L'impostazione predefinita è una volta al minuto. + Il `maximumCallsPerUpload` metodo limita il numero di chiamate effettuate per ogni caricamento. Il valore predefinito è illimitato. + Per impostazione predefinita, l'SDK for Java 2.x pubblica le metriche nello spazio dei nomi. `AwsSdk/JavaSdk2` È possibile utilizzare il `namespace` metodo per specificare un valore diverso. + Per impostazione predefinita, l'SDK pubblica metriche di riepilogo. Le metriche di riepilogo sono costituite da media, minima, massima, somma e numero di campioni. Specificando una o più metriche SDK nel `detailedMetrics` metodo, l'SDK pubblica dati aggiuntivi per ogni metrica. Questi dati aggiuntivi consentono statistiche percentili come p90 e p99 su cui è possibile eseguire interrogazioni. CloudWatch Le metriche dettagliate sono particolarmente utili per le metriche di latenza come`APICallDuration`, che misura la latenza per le richieste dei end-to-end client SDK. Puoi utilizzare i campi della `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` classe per specificare altre metriche SDK comuni. **Passaggi successivi:** se utilizzi anche le funzioni Lambda, consulta [Pubblicare metriche SDK per le AWS Lambda funzioni per la pubblicazione di metriche basate](metric-pub-impl-emf.md) su EMF. # Pubblica le metriche SDK per le funzioni utilizzando il AWS Lambda AWS SDK for Java 2.x Poiché le funzioni Lambda vengono in genere eseguite da millisecondi a minuti, qualsiasi ritardo nell'invio delle metriche, che si verifica con il, rischia la `CloudWatchMetricPublisher` perdita di dati. `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`fornisce un approccio più adatto scrivendo immediatamente le metriche come voci di registro strutturate in [CloudWatch Embedded](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) Metric Format (EMF). `EmfMetricLoggingPublisher`funziona in ambienti di esecuzione dotati di integrazione integrata con Amazon CloudWatch Logs come AWS Lambda Amazon Elastic Container Service. ## Configurazione Prima di poter abilitare e utilizzare le metriche utilizzando`EmfMetricLoggingPublisher`, completa i seguenti passaggi. ### Passaggio 1: aggiungere la dipendenza richiesta Configura le dipendenze del progetto (ad esempio, nel tuo `build.gradle` file `pom.xml` o) per utilizzare la versione `2.30.3` o successiva di. AWS SDK per Java Includi l'`emf-metric-logging-publisher`ArtifactID con il `2.30.3` numero di versione o successivo nelle dipendenze del progetto. Esempio: ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk emf-metric-logging-publisher ``` ### Passaggio 2: configura le autorizzazioni richieste Abilita `logs:PutLogEvents` le autorizzazioni per l'identità IAM utilizzata dall'editore delle metriche per consentire all'SDK for Java di scrivere log in formato EMF. ### Fase 3: Configurazione della registrazione Per garantire una corretta raccolta delle metriche, configura la registrazione in modo che venga inviata alla console a un `INFO` livello o inferiore (ad esempio). `DEBUG` Nel tuo `log4j2.xml` file: ``` ``` Per ulteriori informazioni su come configurare un `log4j2.xml` file, consulta l'[argomento relativo alla registrazione](logging-slf4j.md) in questa guida. ## Configurazione e utilizzo `EmfMetricLoggingPublisher` La seguente classe di funzioni Lambda crea e configura prima un'`EmfMetricLoggingPublisher`istanza e poi la utilizza con un client di servizio Amazon DynamoDB: ``` public class GameIdHandler implements RequestHandler, String> { private final EmfMetricLoggingPublisher emfPublisher; private final DynamoDbClient dynamoDb; public GameIdHandler() { // Build the publisher. this.emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("namespace") .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME) .build(); // Add the publisher to the client. this.dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .region(Region.of(System.getenv("AWS_REGION"))) .build(); } @Override public String handleRequest(Map event, Context context) { Map gameItem = new HashMap<>(); gameItem.put("gameId", AttributeValue.builder().s(event.get("id")).build()); PutItemRequest putItemRequest = PutItemRequest.builder() .tableName("games") .item(gameItem) .build(); dynamoDb.putItem(putItemRequest); return "Request handled"; } } ``` Quando il client DynamoDB esegue il metodo, pubblica automaticamente `putItem` le metriche in un flusso di log in formato EMF. CloudWatch ### Esempio di evento di registro EMF Ad esempio, se invii il seguente evento alla funzione GameHandler Lambda con la registrazione configurata come mostrato in precedenza: ``` { "id": "23456" } ``` Dopo che la funzione ha elaborato l'evento, trovate due eventi di registro simili all'esempio seguente. L'oggetto JSON nel secondo evento contiene i dati metrici Java SDK per l'`PutItem`operazione su DynamoDB. Quando CloudWatch riceve un evento di registro in formato EMF, analizza automaticamente il codice JSON strutturato per estrarre i dati metrici. CloudWatch quindi crea le metriche corrispondenti durante l'archiviazione della voce di registro originale in Logs. CloudWatch ``` 2025-07-11 15:58:30 [main] INFO org.example.GameIdHandler:39 - Received map: {id=23456} 2025-07-11 15:58:34 [main] INFO software.amazon.awssdk.metrics.publishers.emf.EmfMetricLoggingPublisher:43 - { "_aws": { "Timestamp": 1752249513975, "LogGroupName": "/aws/lambda/GameId", "CloudWatchMetrics": [ { "Namespace": "namespace", "Dimensions": [ [ "OperationName", "ServiceId" ] ], "Metrics": [ { "Name": "AvailableConcurrency" }, { "Name": "PendingConcurrencyAcquires" }, { "Name": "ServiceCallDuration", "Unit": "Milliseconds" }, { "Name": "EndpointResolveDuration", "Unit": "Milliseconds" }, { "Name": "MaxConcurrency" }, { "Name": "BackoffDelayDuration", "Unit": "Milliseconds" }, { "Name": "MarshallingDuration", "Unit": "Milliseconds" }, { "Name": "LeasedConcurrency" }, { "Name": "SigningDuration", "Unit": "Milliseconds" }, { "Name": "ConcurrencyAcquireDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallSuccessful" }, { "Name": "RetryCount" }, { "Name": "UnmarshallingDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallDuration", "Unit": "Milliseconds" }, { "Name": "CredentialsFetchDuration", "Unit": "Milliseconds" } ] } ] }, "AvailableConcurrency": 0, "PendingConcurrencyAcquires": 0, "OperationName": "PutItem", "ServiceCallDuration": 1339, "EndpointResolveDuration": 81, "MaxConcurrency": 50, "BackoffDelayDuration": 0, "ServiceId": "DynamoDB", "MarshallingDuration": 181, "LeasedConcurrency": 1, "SigningDuration": 184, "ConcurrencyAcquireDuration": 83, "ApiCallSuccessful": 1, "RetryCount": 0, "UnmarshallingDuration": 85, "ApiCallDuration": 1880, "CredentialsFetchDuration": 138 } ``` La [documentazione dell'API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html) `EmfMetricLoggingPublisher.Builder` mostra le opzioni di configurazione che è possibile utilizzare. È inoltre possibile abilitare la registrazione delle metriche EMF per una singola richiesta, come [mostrato](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request) per. CloudWatchMetricPublisher **Passaggi successivi:** per le applicazioni a esecuzione prolungata, consulta [Pubblicazione delle metriche SDK da applicazioni a esecuzione prolungata per la pubblicazione di metriche](metric-pub-impl-cwmp.md) basate su metriche. CloudWatch # Invia le metriche SDK alla console utilizzando il AWS SDK for Java 2.x L'`[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)`implementazione invia le metriche direttamente nella console o nei file di registro dell'applicazione. Questo approccio è ideale per lo sviluppo, il debug e la comprensione dei parametri raccolti dall'SDK senza richiedere servizi esterni come Amazon. CloudWatch A differenza di `CloudWatchMetricPublisher` and`EmfMetricLoggingPublisher`, `LoggingMetricPublisher` fornisce un output immediato senza ritardi o dipendenze esterne. Ciò lo rende perfetto per lo sviluppo locale e gli scenari di risoluzione dei problemi. ## Quando usare LoggingMetricPublisher Usa `LoggingMetricPublisher` quando devi: + Raccolta di metriche di debug durante lo sviluppo + Scopri quali metriche raccoglie l'SDK per le tue operazioni + Risolvi i problemi di prestazioni a livello locale + Testa la raccolta di metriche senza dipendenze da servizi esterni + Visualizza immediatamente le metriche nella console o nei file di registro **Nota** `LoggingMetricPublisher`non è consigliato per ambienti di produzione in cui sono necessarie funzionalità persistenti di analisi e archiviazione delle metriche. ## Configura la registrazione da console per le metriche Per visualizzare l'`LoggingMetricPublisher`output, configura il framework di registrazione per visualizzare `INFO` i messaggi di livello. La seguente `log4j2.xml` configurazione assicura che le metriche vengano visualizzate nella console: ``` ``` Questa configurazione indirizza l'SDK a inviare le metriche alla console a livello. `INFO` La configurazione del `LoggingMetricPublisher` logger garantisce che l'output metrico venga visualizzato anche se il logger root utilizza un livello superiore come o. `WARN` `ERROR` ## Abilita le metriche della console per un client di servizio L'esempio seguente mostra come creare `LoggingMetricPublisher` e utilizzare un client Amazon Simple Storage Service: ``` import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; // Create a LoggingMetricPublisher with default settings. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Add the publisher to your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build(); // Make requests - metrics will appear in your console. s3Client.listBuckets(); // Clean up resources. metricPublisher.close(); s3Client.close(); ``` ## Scegli il formato di output metrico `LoggingMetricPublisher`supporta due formati di output: + **Formato PLAIN (predefinito):** restituisce le metriche come voci compatte a riga singola + **Formato PRETTY:** emette le metriche in un formato multilinea leggibile dall'uomo L'esempio seguente mostra come utilizzare il formato PRETTY per facilitare la lettura durante lo sviluppo: ``` import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; // Create a LoggingMetricPublisher with PRETTY format. MetricPublisher prettyMetricPublisher = LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY ); // Use with your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(prettyMetricPublisher)) .build(); ``` ## Esempio completo L'esempio seguente dimostra l'utilizzo `LoggingMetricPublisher` in due modi: + A livello di cliente del servizio + Per una singola richiesta ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; /** * Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x. *

* This demo focuses on the S3 listBuckets operation to show how metrics are collected * and logged to the console for development and debugging purposes. *

* LoggingMetricPublisher is ideal for: * - Development and debugging * - Console output for troubleshooting * - Understanding what metrics are being collected * - Testing metric collection without external dependencies */ public class S3LoggingMetricPublisherDemo { private static final Logger logger = LoggerFactory.getLogger(S3LoggingMetricPublisherDemo.class); public static void main(String[] args) { S3LoggingMetricPublisherDemo demo = new S3LoggingMetricPublisherDemo(); demo.demonstrateUsage(); } /** * Demonstrates basic usage with S3Client and metrics enabled at the client level. */ private void demonstrateUsage() { // Create a LoggingMetricPublisher with default settings. The SDK logs metrics as text in a single line. // The default settings are equivalent to using `LoggingMetricPublisher.Format.PLAIN`. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Create an S3 client with metrics enabled. try (S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build()) { // Make the listBuckets request - metrics will be logged to console. ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build()); // The next block shows the using a different LoggingMetricPublisher with a `PRETTY` format. // Since the metric publisher is added to the request using the `overrideConfiguration`, this formatting // applies only to the one request. try { s3Client.listBuckets(ListBucketsRequest.builder() .overrideConfiguration(config -> config .addMetricPublisher(LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY))) .build()); } catch (Exception e) { logger.info("Request failed with metrics logged: {}", e.getMessage()); } logger.info("Found {} buckets in your AWS account.", response.buckets().size()); } catch (Exception e) { logger.error("Error during S3 operation: {}", e.getMessage()); logger.info("Note: This is expected if AWS credentials are not configured."); } // Close the metric publisher to flush any remaining metrics. metricPublisher.close(); } } ``` Il codice registra quanto segue nella console: ``` INFO LoggingMetricPublisher - Metrics published: MetricCollection(name=ApiCall, metrics=[MetricRecord(metric=MarshallingDuration, value=PT0.005409792S), MetricRecord(metric=RetryCount, value=0), MetricRecord(metric=ApiCallSuccessful, value=true), MetricRecord(metric=OperationName, value=ListBuckets), MetricRecord(metric=EndpointResolveDuration, value=PT0.000068S), MetricRecord(metric=ApiCallDuration, value=PT0.163802958S), MetricRecord(metric=CredentialsFetchDuration, value=PT0.145686542S), MetricRecord(metric=ServiceEndpoint, value=https://s3.amazonaws.com), MetricRecord(metric=ServiceId, value=S3)], children=[MetricCollection(name=ApiCallAttempt, metrics=[MetricRecord(metric=TimeToFirstByte, value=PT0.138816S), MetricRecord(metric=SigningDuration, value=PT0.007803459S), MetricRecord(metric=ReadThroughput, value=165153.96002660287), MetricRecord(metric=ServiceCallDuration, value=PT0.138816S), MetricRecord(metric=AwsExtendedRequestId, value=e13Swj3uwn0qP1Oz+m7II5OGq7jf8xxT8H18iDfRBCQmDg+gU4ek91Xrsl8XxRLROlIzCAPQtsQF0DAAWOb8ntuKCzX2AJdj), MetricRecord(metric=HttpStatusCode, value=200), MetricRecord(metric=BackoffDelayDuration, value=PT0S), MetricRecord(metric=TimeToLastByte, value=PT0.148915667S), MetricRecord(metric=AwsRequestId, value=78AW9BM7SWR6YMGB)], children=[MetricCollection(name=HttpClient, metrics=[MetricRecord(metric=MaxConcurrency, value=50), MetricRecord(metric=AvailableConcurrency, value=0), MetricRecord(metric=LeasedConcurrency, value=1), MetricRecord(metric=ConcurrencyAcquireDuration, value=PT0.002623S), MetricRecord(metric=PendingConcurrencyAcquires, value=0), MetricRecord(metric=HttpClientName, value=Apache)], children=[])])]) INFO LoggingMetricPublisher - [4e6f2bb5] ApiCall INFO LoggingMetricPublisher - [4e6f2bb5] ┌──────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MarshallingDuration=PT0.000063S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ RetryCount=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallSuccessful=true │ INFO LoggingMetricPublisher - [4e6f2bb5] │ OperationName=ListBuckets │ INFO LoggingMetricPublisher - [4e6f2bb5] │ EndpointResolveDuration=PT0.000024375S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallDuration=PT0.018463083S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ CredentialsFetchDuration=PT0.000022334S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceEndpoint=https://s3.amazonaws.com │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceId=S3 │ INFO LoggingMetricPublisher - [4e6f2bb5] └──────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] ApiCallAttempt INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToFirstByte=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ SigningDuration=PT0.000301125S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ReadThroughput=1195591.792850103 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceCallDuration=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsExtendedRequestId=3QI1eenRuokdszWqZBmBMDUmko6FlSmHkM+CUMNMeLor7gJml4D4lv6QXUZ1zWoTgG+tHbr6yo2vHdz4h1P8PDovvtMFRCeB │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpStatusCode=200 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ BackoffDelayDuration=PT0S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToLastByte=PT0.017952625S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsRequestId=78AVFAF795AAWAXH │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] HttpClient INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MaxConcurrency=50 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AvailableConcurrency=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ LeasedConcurrency=1 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ConcurrencyAcquireDuration=PT0.00004S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ PendingConcurrencyAcquires=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpClientName=Apache │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────┘ INFO S3LoggingMetricPublisherDemo - Found 6 buckets in your AWS account. ``` ### Artefatti aggiuntivi per l'esempio File Maven `pom.xml` ``` 4.0.0 com.example s3-logging-metric-publisher-demo 1.0.0 jar AWS S3 LoggingMetricPublisher Demo Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x 17 17 UTF-8 2.31.66 2.24.3 software.amazon.awssdk bom ${aws.java.sdk.version} pom import org.apache.logging.log4j log4j-bom ${log4j.version} pom import software.amazon.awssdk s3 org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-core org.apache.maven.plugins maven-compiler-plugin 3.13.0 17 17 ``` File di configurazione `Log4j2.xml` ``` ``` Le metriche includono informazioni sulla tempistica, dettagli del servizio, nomi delle operazioni e codici di stato HTTP che aiutano a comprendere i modelli di utilizzo delle API dell' AWS applicazione. ## Fasi successive Dopo l'utilizzo `LoggingMetricPublisher` per lo sviluppo e il debug, considera queste opzioni per gli ambienti di produzione: + Per le applicazioni a lunga durata, utilizzalo [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)per inviare metriche ad Amazon CloudWatch per analisi e avvisi + Per quanto riguarda AWS Lambda le funzioni, utilizza per [EmfMetricLoggingPublisher](metric-pub-impl-emf.md)pubblicare le metriche in formato Embedded Metric CloudWatch # AWS SDK for Java 2.x: Riferimento completo alle metriche [Con AWS SDK for Java 2.x, puoi raccogliere metriche dai client di servizio nella tua applicazione e quindi pubblicarle (emettere) tali metriche su Amazon. CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) Queste tabelle elencano le metriche che puoi raccogliere e qualsiasi requisito di utilizzo del client HTTP. [Per ulteriori informazioni sull'abilitazione e la configurazione delle metriche per l'SDK, consulta Abilitazione delle metriche SDK.](metrics.md) ## Metriche raccolte con ogni richiesta | Nome parametro | Description | Tipo | | --- | --- | --- | | ApiCallDuration | La durata della chiamata API. Sono inclusi tutti i tentativi di chiamata effettuati. | Durata\$1 | | ApiCallSuccessful | Vero se la chiamata API è riuscita, falso in caso contrario. | Booleano | | CredentialsFetchDuration | Il periodo di tempo necessario per recuperare le credenziali di firma per la chiamata API. | Durata\$1 | | EndpointResolveDuration | Il periodo di tempo necessario per risolvere l'endpoint utilizzato per la chiamata API. | Durata\$1 | | MarshallingDuration | Il periodo di tempo necessario per adattare la richiesta SDK a una richiesta HTTP. | Durata\$1 | | OperationName | Il nome dell'operazione di servizio richiamata. | Stringa | | RetryCount | Il numero di tentativi eseguiti dall'SDK nell'esecuzione della richiesta. 0 implica che la richiesta ha funzionato la prima volta e che non è stato effettuato alcun tentativo. Per ulteriori informazioni sulla configurazione del comportamento dei nuovi tentativi, consulta. [Strategie di nuovo tentativo](retry-strategy.md#retry-strategies) | Numero intero | | ServiceId | L'ID univoco del servizio. | Stringa | | ServiceEndpoint | L'endpoint del servizio. | URI | | TokenFetchDuration | Il periodo di tempo necessario per recuperare le credenziali di firma per la chiamata API. | Durata\$1 | [\$1 java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) ## Metriche raccolte per ogni tentativo di richiesta Ogni chiamata API potrebbe richiedere più tentativi prima di ricevere una risposta. Queste metriche vengono raccolte per ogni tentativo. ### Metriche principali | Nome parametro | Description | Tipo | | --- | --- | --- | | AwsExtendedRequestId | L'ID della richiesta estesa della richiesta di servizio. | Stringa | | AwsRequestId | L'ID della richiesta di servizio. | Stringa | | BackoffDelayDuration | Il periodo di attesa dell'SDK prima di questo tentativo di chiamata API. Il valore si basa sul `[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)` set sul client. Per ulteriori informazioni, consulta la [Strategie di nuovo tentativo](retry-strategy.md#retry-strategies) sezione di questa guida. | Durata\$1 | | ErrorType | Il tipo di errore che si è verificato durante un tentativo di chiamata. I seguenti sono i valori possibili: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) | Stringa | | ReadThroughput | La velocità effettiva di lettura del client, definita come. `NumberOfResponseBytesRead / (TTLB - TTFB)` Questo valore è espresso in byte al secondo. Nota che questa metrica misura solo i byte letti dall'interno di o. `ResponseTransformer` `AsyncResponseTransformer` I dati letti all'esterno del trasformatore, ad esempio quando il flusso di risposta viene restituito come risultato del trasformatore, non sono inclusi nel calcolo. | Double | | WriteThroughput | La velocità effettiva di scrittura del client, definita come. `RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)` Questo valore è espresso in byte al secondo. Questa metrica misura la velocità con cui l'SDK fornisce il corpo della richiesta al client HTTP. Sono esclusi la configurazione della connessione, il tempo di handshake TLS e il tempo di elaborazione del server. Questa metrica viene riportata solo per le richieste che hanno un corpo di streaming come S3. PutObject Tieni presente che questa metrica non tiene conto del buffering nel livello client HTTP. La velocità di trasmissione effettiva della rete potrebbe essere inferiore se il client HTTP memorizza i dati nel buffer prima dell'invio. Questa metrica rappresenta il limite superiore del throughput di rete. | Double | | ServiceCallDuration | Il periodo di tempo necessario per connettersi al servizio (o acquisire una connessione dal pool di connessioni), inviare la richiesta serializzata e ricevere la risposta iniziale (ad esempio il codice di stato HTTP e le intestazioni). Ciò NON include il tempo necessario per leggere l'intera risposta dal servizio. | Durata\$1 | | SigningDuration | Il periodo di tempo necessario per firmare la richiesta HTTP. | Durata\$1 | | TimeToFirstByte | Periodo di tempo compreso tra l'invio della richiesta HTTP (inclusa l'acquisizione di una connessione) al servizio e la ricezione del primo byte delle intestazioni della risposta. | Durata\$1 | | TimeToLastByte | Periodo di tempo compreso tra l'invio della richiesta HTTP (inclusa l'acquisizione di una connessione) al servizio e la ricezione dell'ultimo byte della risposta. Tieni presente APIs che per le risposte in streaming di ritorno, questa metrica copre il tempo fino al completamento dell'o. `ResponseTransformer` `AsyncResponseTransformer` | Durata\$1 | | UnmarshallingDuration | Il periodo di tempo necessario per annullare il marshall della risposta HTTP a una risposta SDK. Nota: per le operazioni di streaming, questo non include il tempo necessario per leggere il payload di risposta. | Durata\$1 | [\$1 java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) ### Metriche HTTP | Nome parametro | Description | Tipo | Client HTTP richiesto\$1 | | --- | --- | --- | --- | | AvailableConcurrency | Il numero di richieste simultanee aggiuntive supportate dal client HTTP senza stabilire nuove connessioni al server di destinazione. Per le operazioni HTTP/1, questo è uguale al numero di connessioni TCP inattive stabilite con il servizio. Per le operazioni HTTP/2, questo è uguale al numero di flussi inattivi. Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | ConcurrencyAcquireDuration | Il periodo di tempo necessario per acquisire un canale dal pool di connessioni. Per le operazioni HTTP/1, un canale equivale a una connessione TCP. Per le operazioni HTTP/2, un canale è uguale a un canale di flusso HTTP/2. L'acquisizione di un nuovo canale può includere del tempo per: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) | Durata\$1 | Apache, Netty, CRT | | HttpClientName | Il nome dell'HTTP utilizzato per la richiesta. | Stringa | Apache, Netty, CRT | | HttpStatusCode | Il codice di stato della risposta HTTP. | Numero intero | Qualsiasi | | LeasedConcurrency | Il numero di richieste attualmente eseguite dal client HTTP. Per le operazioni HTTP/1, questo è uguale al numero di connessioni TCP attive con il servizio (escluse le connessioni inattive). Per le operazioni HTTP/2, questo è uguale al numero di flussi HTTP attivi con il servizio (esclusa la capacità del flusso inattivo). Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | LocalStreamWindowSize | La dimensione della finestra HTTP/2 locale in byte per il flusso che esegue questa richiesta. | Numero intero | Netty | | MaxConcurrency | Il numero massimo di richieste simultanee supportate dal client HTTP. Per le operazioni HTTP/1, questo è uguale al numero massimo di connessioni TCP che il client HTTP può raggruppare. Per le operazioni HTTP/2, questo è uguale al numero massimo di flussi che il client HTTP può raggruppare. Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | PendingConcurrencyAcquires | Il numero di richieste che attendono la concorrenza dal client HTTP. Per le operazioni HTTP/1, questo è uguale al numero di richieste in attesa che venga stabilita o restituita una connessione TCP dal pool di connessioni. Per le operazioni HTTP/2, questo è uguale al numero di richieste in attesa di un nuovo flusso (e possibilmente di una nuova connessione HTTP/2) dal pool di connessioni. Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | RemoteStreamWindowSize | La dimensione della finestra HTTP/2 remota in byte per il flusso che esegue questa richiesta. | Numero intero | Netty | \$1 [java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). I termini usati nella colonna significano: + Apache: il client HTTP basato su Apache () `[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)` + Netty: il client HTTP basato su Netty () `[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)` + CRT: il client HTTP basato su AWS CRT () `[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)` + Qualsiasi: la raccolta di dati metrici non dipende dal client HTTP, incluso il client HTTP URLConnection basato () `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)` # AWS SDK for Java 2.x Applicazioni di monitoraggio Il monitoraggio è una parte importante del mantenimento dell'affidabilità, della disponibilità e delle prestazioni delle applicazioni che utilizzano. AWS SDK for Java 2.x AWS fornisce i seguenti strumenti di monitoraggio per controllare SDK for Java 2.x, segnalare quando qualcosa non va e intraprendere azioni automatiche quando appropriato: + *Amazon CloudWatch* monitora AWS le tue risorse e le applicazioni su cui esegui AWS in tempo reale. Puoi raccogliere i parametri e tenerne traccia, creare pannelli di controllo personalizzati e impostare allarmi per inviare una notifica o intraprendere azioni quando un parametro specificato raggiunge una determinata soglia. Ad esempio, puoi tenere CloudWatch traccia dell'utilizzo della CPU o di altri parametri delle tue EC2 istanze Amazon e avviare automaticamente nuove istanze quando necessario. Per ulteriori informazioni, consulta la [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). + *Amazon CloudWatch Logs* ti consente di monitorare, archiviare e accedere ai tuoi file di registro da EC2 istanze Amazon e altre fonti. CloudTrail CloudWatch I log possono monitorare le informazioni contenute nei file di registro e avvisarti quando vengono raggiunte determinate soglie. Puoi inoltre archiviare i dati del log in storage estremamente durevole. Per ulteriori informazioni, consulta la [Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/). + *AWS CloudTrail*acquisisce le chiamate API e gli eventi correlati effettuati da o per conto del tuo AWS account e invia i file di log a un bucket Amazon S3 da te specificato. Puoi identificare quali utenti e account hanno chiamato AWS, l'indirizzo IP di origine da cui sono state effettuate le chiamate e quando sono avvenute le chiamate. Per ulteriori informazioni, consulta la [Guida per l'utente AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/). # Registrazione con l'SDK for Java 2.x AWS SDK for Java 2.x Utilizza [SLF4J](https://www.slf4j.org/manual.html), che è un livello di astrazione che consente l'uso di uno qualsiasi dei diversi sistemi di registrazione in fase di esecuzione. I sistemi di registrazione supportati includono, tra gli altri, Java Logging Framework e Apache [Log4j](https://logging.apache.org/log4j/2.x/) 2. Questo argomento mostra come utilizzare Log4j 2 come sistema di registrazione per lavorare con l'SDK. ## File di configurazione Log4j 2 In genere si utilizza un file di configurazione, denominato `log4j2.xml` Log4j 2. File di configurazione di esempio sono mostrati di seguito. Per ulteriori informazioni sui valori utilizzati nel file di configurazione, consulta il [manuale per la configurazione di Log4j](https://logging.apache.org/log4j/2.x/manual/configuration.html). Il `log4j2.xml` file deve trovarsi nel classpath all'avvio dell'applicazione. Per un progetto Maven, inserisci il file nella directory. `/src/main/resources` [Il file di `log4j2.xml` configurazione specifica proprietà come il [livello di registrazione](https://logging.apache.org/log4j/2.x/manual/configuration.html#Loggers), a cui viene inviato l'output di registrazione (ad esempio, [a un file o alla console) e il](https://logging.apache.org/log4j/2.x/manual/appenders.html) formato dell'output.](https://logging.apache.org/log4j/2.x/manual/layouts.html) Il livello di registrazione specifica il livello di dettaglio emesso da Log4j 2. [https://logging.apache.org/log4j/2.x/manual/architecture.html#](https://logging.apache.org/log4j/2.x/manual/architecture.html#) Il livello di registrazione è impostato in modo indipendente per ogni gerarchia. La gerarchia di registrazione principale che si utilizza con è. AWS SDK for Java 2.x `software.amazon.awssdk` ## Aggiungi dipendenza dalla registrazione Per configurare l'associazione Log4j 2 per SLF4 J nel tuo file di build, usa quanto segue. ------ #### [ Maven ] Aggiungi i seguenti elementi al tuo `pom.xml` file. ``` ... org.apache.logging.log4j log4j-slf4j2-impl VERSION ... ``` ------ #### [ Gradle–Kotlin DSL ] Aggiungi quanto segue al tuo `build.gradle.kts` file. ``` ... dependencies { ... implementation("org.apache.logging.log4j:log4j-slf4j2-impl:VERSION") ... } ... ``` ------ Usa `2.20.0` per la versione minima dell'`log4j-slf4j2-impl`artefatto. Per la versione più recente, usa la versione pubblicata su [Maven](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-slf4j2-impl) Central. Sostituisci *VERSION* con la versione che utilizzerai. ## Errori e avvisi specifici dell'SDK Ti consigliamo di lasciare sempre la gerarchia dei logger «software.amazon.awssdk» impostata su «WARN» per catturare eventuali messaggi importanti dalle librerie client dell'SDK. Ad esempio, se il client Amazon S3 rileva che l'applicazione non ha chiuso correttamente `InputStream` e che potrebbe esserci una perdita di risorse, il client S3 lo segnala tramite un messaggio di avviso ai log. Questo garantisce inoltre che i messaggi vengono registrati se il client presenta problemi di gestione delle richieste o delle risposte. *Il `log4j2.xml` file seguente lo imposta su «WARN», che genera l'output di messaggi di avviso e `rootLogger` a livello di errore da tutti i logger dell'applicazione, inclusi quelli nella gerarchia «software.amazon.awssdk».* In alternativa, puoi impostare esplicitamente la gerarchia dei logger «software.amazon.awssdk» su «WARN», se utilizzata. `` **Esempio di file di configurazione Log4j2.xml** Questa configurazione registrerà i messaggi ai livelli «ERROR» e «WARN» nella console per tutte le gerarchie di logger. ``` ``` ## Registrazione riassuntiva di richieste/risposte Ogni richiesta a un Servizio AWS genera un ID di AWS richiesta univoco, utile in caso di problemi relativi alla gestione di Servizio AWS una richiesta. AWS IDs le richieste sono accessibili a livello di codice tramite [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId())oggetti nell'SDK per qualsiasi chiamata di servizio non riuscita e possono anche essere segnalate tramite il livello di registro «DEBUG» del logger «software.amazon.awssdk.request». Il file seguente consente un riepilogo delle richieste e delle risposte. `log4j2.xml` ``` ``` Di seguito è riportato un esempio di output del log: ``` 2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length, Content-Type, User-Agent, X-Amz-Target], queryParameters=[]) 2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: not available ``` Se sei interessato solo all'ID della richiesta, usa``. ## Registrazione SDK a livello di debug Se hai bisogno di maggiori dettagli su ciò che sta facendo l'SDK, puoi impostare il livello di registrazione del logger su. `software.amazon.awssdk` `DEBUG` A questo livello, l'SDK genera una grande quantità di dettagli, quindi ti consigliamo di impostare questo livello per risolvere gli errori utilizzando i test di integrazione. A questo livello di registrazione, l'SDK registra le informazioni sulla configurazione, la risoluzione delle credenziali, gli intercettori di esecuzione, l'attività TLS di alto livello, la firma delle richieste e molto altro. Di seguito è riportato un esempio di istruzioni emesse dall'SDK a livello di chiamata. `DEBUG` `S3Client#listBuckets()` ``` DEBUG s.a.a.r.p.AwsRegionProviderChain:57 - Unable to load region from software.amazon.awssdk.regions.providers.SystemSettingsRegionProvider@324dcd31:Unable to load region from system settings. Region must be specified either via environment variable (AWS_REGION) or system property (aws.region). DEBUG s.a.a.c.i.h.l.ClasspathSdkHttpServiceProvider:85 - The HTTP implementation loaded is software.amazon.awssdk.http.apache.ApacheSdkHttpService@a23a01d DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@69b2f8e5, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@6331250e, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@a10c1b5, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@644abb8f, software.amazon.awssdk.services.s3.auth.scheme.internal.S3AuthSchemeInterceptor@1a411233, software.amazon.awssdk.services.s3.endpoints.internal.S3ResolveEndpointInterceptor@70325d20, software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa, software.amazon.awssdk.services.s3.internal.handlers.StreamingRequestInterceptor@4d847d32, software.amazon.awssdk.services.s3.internal.handlers.CreateBucketInterceptor@5f462e3b, software.amazon.awssdk.services.s3.internal.handlers.CreateMultipartUploadRequestInterceptor@3d7fa3ae, software.amazon.awssdk.services.s3.internal.handlers.DecodeUrlEncodedResponseInterceptor@58065f0c, software.amazon.awssdk.services.s3.internal.handlers.GetBucketPolicyInterceptor@3605c4d3, software.amazon.awssdk.services.s3.internal.handlers.S3ExpressChecksumInterceptor@585c13de, software.amazon.awssdk.services.s3.internal.handlers.AsyncChecksumValidationInterceptor@187eb9a8, software.amazon.awssdk.services.s3.internal.handlers.SyncChecksumValidationInterceptor@726a6b94, software.amazon.awssdk.services.s3.internal.handlers.EnableTrailingChecksumInterceptor@6ad11a56, software.amazon.awssdk.services.s3.internal.handlers.ExceptionTranslationInterceptor@522b2631, software.amazon.awssdk.services.s3.internal.handlers.GetObjectInterceptor@3ff57625, software.amazon.awssdk.services.s3.internal.handlers.CopySourceInterceptor@1ee29c84, software.amazon.awssdk.services.s3.internal.handlers.ObjectMetadataInterceptor@7c8326a4] DEBUG s.a.a.u.c.CachedSupplier:85 - (SsoOidcTokenProvider()) Cached value is stale and will be refreshed. ... DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@51351f28, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@21618fa7, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@15f2eda3, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@34cf294c, software.amazon.awssdk.services.sso.auth.scheme.internal.SsoAuthSchemeInterceptor@4d7aaca2, software.amazon.awssdk.services.sso.endpoints.internal.SsoResolveEndpointInterceptor@604b1e1d, software.amazon.awssdk.services.sso.endpoints.internal.SsoRequestSetEndpointInterceptor@62566842] ... DEBUG s.a.a.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=GET, protocol=https, host=portal.sso.us-east-1.amazonaws.com, encodedPath=/federation/credentials, headers=[amz-sdk-invocation-id, User-Agent, x-amz-sso_bearer_token], queryParameters=[role_name, account_id]) DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: smithy.api#noAuth DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to portal.sso.us-east-1.amazonaws.com/18.235.195.183:443 with timeout 2000 ... DEBUG s.a.a.requestId:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available DEBUG s.a.a.request:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available DEBUG s.a.a.u.c.CachedSupplier:85 - (software.amazon.awssdk.services.sso.auth.SsoCredentialsProvider@b965857) Successfully refreshed cached value. Next Prefetch Time: 2024-04-25T22:03:10.097Z. Next Stale Time: 2024-04-25T22:05:30Z DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Interceptor 'software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa' modified the message with its modifyHttpRequest method. ... DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: aws.auth#sigv4 ... DEBUG s.a.a.a.s.Aws4Signer:85 - AWS4 Canonical Request: GET ... DEBUG s.a.a.h.a.a.i.s.DefaultV4RequestSigner:85 - AWS4 String to sign: AWS4-HMAC-SHA256 20240425T210631Z 20240425/us-east-1/s3/aws4_request aafb7784627fa7a49584256cb746279751c48c2076f813259ef767ecce304d64 DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to s3.us-east-1.amazonaws.com/52.217.41.86:443 with timeout 2000 ... ``` Il `log4j2.xml` file seguente configura l'output precedente. ``` ``` ## Abilita la registrazione dei cavi Può essere utile visualizzare le richieste e le risposte esatte che l'SDK for Java 2.x invia e riceve. Se è necessario accedere a queste informazioni, è possibile abilitarle temporaneamente aggiungendo la configurazione necessaria in base al client HTTP utilizzato dal client di servizio. Per impostazione predefinita, i client di servizio sincroni, come [S3Client, utilizzano un Apache sottostante, mentre i client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html) di servizio asincroni HttpClient, come [S3 AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html), utilizzano un client HTTP non bloccante Netty. Di seguito è riportato un elenco dettagliato dei client HTTP che è possibile utilizzare per le due categorie di client di servizio: | Client HTTP sincroni | Client HTTP asincroni | | --- | --- | | [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) (predefinito) | [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) (predefinito) | | [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) | [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) | | [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) | | | [Apache 5 HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) | Consulta la scheda appropriata di seguito per le impostazioni di configurazione che devi aggiungere in base al client HTTP sottostante. **avvertimento** Ti consigliamo di usare la registrazione in rete solo per scopi di debug. È opportuno disabilitarla negli ambienti di produzione in quanto può registrare dati sensibili. L'intera richiesta o risposta senza crittografia viene registrata, anche per una chiamata HTTPS. Per richieste di grandi dimensioni (ad esempio, per caricare un file Amazon S3) o risposte, anche il verbose wire logging può influire in modo significativo sulle prestazioni dell'applicazione. ------ #### [ ApacheHttpClient ] Aggiungi il logger «org.apache.http.wire» al file di `log4j2.xml` configurazione e imposta il livello su «DEBUG». Il seguente `log4j2.xml` file attiva la registrazione cablata completa per Apache. HttpClient ``` ``` È necessaria un'ulteriore dipendenza di Maven dall'`log4j-1.2-api`artefatto per la registrazione via cavo con Apache, poiché utilizza 1.2 sotto il cofano. Il set completo di dipendenze Maven per log4j 2, incluso il wire logging per il client HTTP Apache, è mostrato nei seguenti frammenti di file di build. **Maven** ``` ... ... org.apache.logging.log4j log4j-bom VERSION pom import ... org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-1.2-api ... ``` **DSL Gradle-Kotlin** ``` ... dependencies { ... implementation(platform("org.apache.logging.log4j:log4j-bom:VERSION")) implementation("org.apache.logging.log4j:log4j-slf4j2-impl") implementation("org.apache.logging.log4j:log4j-1.2-api") } ... ``` Usa `2.20.0` per la versione minima dell'artefatto. `log4j-bom` Per la versione più recente, usa la versione pubblicata su [Maven](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-bom) Central. Sostituisci *VERSION* con la versione che utilizzerai. ------ #### [ Apache5HttpClient ] Aggiungi il logger «org.apache.hc.client5.http.wire» al file di configurazione e imposta il livello su «DEBUG». `log4j2.xml` `log4j2.xml`Il seguente file attiva la registrazione cablata completa per Apache5. HttpClient ``` ``` ------ #### [ UrlConnectionHttpClient ] Per registrare i dettagli dei client di servizio che utilizzano il`UrlConnectionHttpClient`, create innanzitutto un `logging.properties` file con i seguenti contenuti: ``` handlers=java.util.logging.ConsoleHandler java.util.logging.ConsoleHandler.level=FINEST sun.net.www.protocol.http.HttpURLConnection.level=ALL ``` Imposta la seguente proprietà del sistema JVM con il percorso completo di: `logging.properties` ``` -Djava.util.logging.config.file=/full/path/to/logging.properties ``` Questa configurazione registrerà solo le intestazioni della richiesta e della risposta, ad esempio: ``` FINE: sun.net.www.MessageHeader@35a9782c11 pairs: {GET /fileuploadtest HTTP/1.1: null}{amz-sdk-invocation-id: 5f7e707e-4ac5-bef5-ba62-00d71034ffdc}{amz-sdk-request: attempt=1; max=4}{Authorization: AWS4-HMAC-SHA256 Credential=/20220927/us-east-1/s3/aws4_request, SignedHeaders=amz-sdk-invocation-id;amz-sdk-request;host;x-amz-content-sha256;x-amz-date;x-amz-te, Signature=e367fa0bc217a6a65675bb743e1280cf12fbe8d566196a816d948fdf0b42ca1a}{User-Agent: aws-sdk-java/2.17.230 Mac_OS_X/12.5 OpenJDK_64-Bit_Server_VM/25.332-b08 Java/1.8.0_332 vendor/Amazon.com_Inc. io/sync http/UrlConnection cfg/retry-mode/legacy}{x-amz-content-sha256: UNSIGNED-PAYLOAD}{X-Amz-Date: 20220927T133955Z}{x-amz-te: append-md5}{Host: tkhill-test1.s3.amazonaws.com}{Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2}{Connection: keep-alive} FINE: sun.net.www.MessageHeader@70a36a6611 pairs: {null: HTTP/1.1 200 OK}{x-amz-id-2: sAFeZDOKdUMsBbkdjyDZw7P0oocb4C9KbiuzfJ6TWKQsGXHM/dFuOvr2tUb7Y1wEHGdJ3DSIxq0=}{x-amz-request-id: P9QW9SMZ97FKZ9X7}{Date: Tue, 27 Sep 2022 13:39:57 GMT}{Last-Modified: Tue, 13 Sep 2022 14:38:12 GMT}{ETag: "2cbe5ad4a064cedec33b452bebf48032"}{x-amz-transfer-encoding: append-md5}{Accept-Ranges: bytes}{Content-Type: text/plain}{Server: AmazonS3}{Content-Length: 67} ``` Per vedere i request/response corpi, aggiungili `-Djavax.net.debug=all` alle proprietà JVM. Questa proprietà aggiuntiva registra una grande quantità di informazioni, incluse tutte le informazioni SSL. Nella console di registro o nel file di registro, cercate `"GET"` o accedete rapidamente `"POST"` alla sezione del registro contenente le richieste e le risposte effettive. Cerca `"Plaintext before ENCRYPTION"` le richieste e le risposte `"Plaintext after DECRYPTION"` per visualizzare il testo completo delle intestazioni e dei corpi. ------ #### [ NettyNioAsyncHttpClient ] Se il client di servizio asincrono utilizza l'impostazione predefinita`NettyNioAsyncHttpClient`, aggiungi due logger aggiuntivi al `log4j2.xml` file per registrare le intestazioni HTTP e i corpi di richiesta/risposta. ``` ``` Ecco un esempio completo: `log4j2.xml` ``` ``` Queste impostazioni registrano tutti i dettagli e i request/response corpi delle intestazioni. ------ #### [ AwsCrtAsyncHttpClient/AwsCrtHttpClient ] Se il client di servizio è stato configurato per utilizzare un'istanza di un client HTTP AWS basato su CRT, è possibile registrare i dettagli impostando le proprietà del sistema JVM o a livello di codice. | | | --- | | Log to a file at "Debug" level | | Utilizzo delle proprietà di sistema: 

-Daws.crt.log.level=Trace 
-Daws.crt.log.destination=File 
-Daws.crt.log.filename=
| A livello di codice: 
import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK service client.
Log.initLoggingToFile(Log.LogLevel.Trace, "");
| | Log to the console at "Debug" level | | Utilizzo delle proprietà del sistema: 
-Daws.crt.log.level=Trace 
-Daws.crt.log.destination=Stdout
| A livello di codice: 
import software.amazon.awssdk.crt.Log;

// Execute this statement before constructing the SDK service client.
Log.initLoggingToStdout(Log.LogLevel.Trace);
| Per motivi di sicurezza, a livello «Trace» i client HTTP AWS basati su CRT registrano solo le intestazioni di risposta. Le intestazioni delle richieste, i corpi delle richieste e i corpi delle risposte non vengono registrati. ------ # Configurazione degli endpoint client in AWS SDK for Java 2.x L'SDK for Java 2.x offre diversi modi per configurare gli endpoint del servizio. Un endpoint è l'URL utilizzato dall'SDK per effettuare chiamate API. Servizi AWS Per impostazione predefinita, l'SDK determina automaticamente l'endpoint appropriato per ogni servizio in base a quello Regione AWS che hai configurato. Tuttavia, ci sono scenari in cui potresti dover personalizzare o sostituire questi endpoint: + Utilizzo di implementazioni di servizi locali o di terze parti (ad esempio) LocalStack + Connessione Servizi AWS tramite un proxy o un endpoint VPC + Test su endpoint di servizio in versione beta o precedente al rilascio ## Opzioni di configurazione degli endpoint AWS SDK for Java 2.x Fornisce diversi modi per configurare gli endpoint: + Configurazione integrata nel codice utilizzando il service client builder + Configurazione esterna con variabili di ambiente + Configurazione esterna con proprietà del sistema JVM + Configurazione esterna con file di configurazione condiviso AWS ## Configurazione degli endpoint incorporata nel codice ### Uso di `endpointOverride` Il modo più diretto per configurare un endpoint consiste nell'utilizzare il `endpointOverride` metodo sul service client builder. Questo metodo accetta un `URI` oggetto che rappresenta l'URL dell'endpoint personalizzato. **Example Impostazione di un endpoint personalizzato per un client Amazon S3** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import java.net.URI; S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .endpointOverride(URI.create("https://my-custom-s3-endpoint.example.com")) .build(); ``` Durante l'utilizzo`endpointOverride`, devi comunque specificare una regione per il client, anche se l'endpoint viene impostato in modo esplicito. La regione viene utilizzata per firmare le richieste. ### Rilevamento di endpoint Alcuni Servizi AWS supportano l'endpoint discovery, in cui l'SDK può scoprire automaticamente l'endpoint ottimale da utilizzare. È possibile abilitare o disabilitare questa funzionalità utilizzando il `endpointDiscoveryEnabled` metodo del service client builder. **Example Abilitazione del rilevamento degli endpoint per un client DynamoDB** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; DynamoDbClient dynamoDb = DynamoDbClient.builder() .region(Region.US_WEST_2) .endpointDiscoveryEnabled(true) .build(); ``` ## Configurazione degli endpoint a livello di richiesta In alcuni casi, potrebbe essere necessario sovrascrivere l'endpoint per una richiesta specifica mentre si utilizza lo stesso client per altre richieste con l'endpoint predefinito. Lo AWS SDK for Java 2.x supporta tramite l'override delle richieste. **Example Sovrascrivere l'endpoint per una richiesta specifica** ``` import software.amazon.awssdk.core.SdkRequest; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.GetObjectRequest; import software.amazon.awssdk.http.SdkHttpRequest; S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .build(); // Create a request GetObjectRequest getObjectRequest = GetObjectRequest.builder() .bucket("amzn-s3-demo-bucket") .key("my-key") .overrideConfiguration(c -> c.putHeader("Host", "custom-endpoint.example.com")) .build(); // Execute the request with the custom endpoint s3.getObject(getObjectRequest); ``` Tieni presente che le sostituzioni degli endpoint a livello di richiesta sono limitate e potrebbero non funzionare per tutti i servizi o gli scenari. Nella maggior parte dei casi, si consiglia di utilizzare la configurazione degli endpoint a livello di client. ## Configurazione degli endpoint esterni ### Utilizzo delle variabili di ambiente È possibile configurare gli endpoint utilizzando variabili di ambiente. L'SDK supporta la configurazione degli endpoint specifici del servizio tramite variabili di ambiente nel formato`AWS_ENDPOINT_URL_[SERVICE]`, dove `[SERVICE]` è l'identificatore di servizio in maiuscolo. **Example Impostazione di un endpoint S3 utilizzando variabili di ambiente** ``` # For Linux/macOS export AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com # For Windows set AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com ``` Puoi anche impostare un prefisso o suffisso URL globale dell'endpoint utilizzando le seguenti variabili di ambiente: + `AWS_ENDPOINT_URL`- Imposta un endpoint globale per tutti i servizi + `AWS_ENDPOINT_URL_PREFIX`- Aggiunge un prefisso a tutti gli endpoint di servizio + `AWS_ENDPOINT_URL_SUFFIX`- Aggiunge un suffisso a tutti gli endpoint di servizio ### Utilizzo delle proprietà del sistema JVM È inoltre possibile configurare gli endpoint utilizzando le proprietà del sistema JVM. Il formato è simile alle variabili di ambiente ma utilizza una convenzione di denominazione diversa. **Example Impostazione di un endpoint S3 utilizzando le proprietà del sistema JVM** ``` java -Daws.endpointUrl.s3=https://my-custom-s3-endpoint.example.com -jar your-application.jar ``` La configurazione globale degli endpoint è disponibile anche tramite le proprietà del sistema: + `aws.endpointUrl`- Imposta un endpoint globale per tutti i servizi + `aws.endpointUrl.prefix`- Aggiunge un prefisso a tutti gli endpoint di servizio + `aws.endpointUrl.suffix`- Aggiunge un suffisso a tutti gli endpoint di servizio ### Utilizzo del file di configurazione condiviso AWS Supporta AWS SDK for Java 2.x anche la configurazione degli endpoint tramite il file di AWS configurazione condiviso, in genere situato in `~/.aws/config` (Linux/macOS) o (Windows). `%USERPROFILE%\.aws\config` Consulta la guida di riferimento [AWS SDKs and Tools per informazioni ed esempi](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html#ss-endpoints-config). ## Precedenza della configurazione Quando sono presenti più configurazioni di endpoint, l'SDK segue questo ordine di precedenza (dal più alto al più basso): 1. Sostituzioni a livello di richiesta (se applicabile) 1. Configurazione a livello di client tramite `endpointOverride` 1. Variabili di ambiente 1. Proprietà del sistema JVM 1. File di configurazione condiviso AWS 1. Endpoint predefiniti in base a quelli configurati Regione AWS ## Configurazione degli endpoint specifica del servizio Alcuni Servizi AWS dispongono di opzioni di configurazione degli endpoint aggiuntive specifiche per quel servizio. Di seguito si riportano alcuni esempi: ### Configurazione degli endpoint Amazon S3 Amazon S3 supporta diverse configurazioni di endpoint tramite la classe: `S3Configuration` + `dualstackEnabled`- Abilita il supporto IPv6 + `accelerateModeEnabled`- Abilita l'accelerazione del trasferimento S3 + `pathStyleAccessEnabled`- Utilizza l'accesso in stile path anziché lo stile ospitato virtualmente + `useArnRegionEnabled`- Utilizza la regione di un ARN per le richieste interregionali + `fipsModeEnabled`- Instrada le richieste verso endpoint conformi a FIPS **Example Configurazione delle opzioni di endpoint specifiche per S3** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.S3Configuration; S3Client s3 = S3Client.builder() .region(Region.US_WEST_2) .serviceConfiguration(S3Configuration.builder() .accelerateModeEnabled(true) .dualstackEnabled(true) .pathStyleAccessEnabled(false) .fipsModeEnabled(true) .build()) .build(); ``` ### Configurazione degli endpoint DynamoDB Per DynamoDB, potresti voler utilizzare l'endpoint discovery o connetterti a [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) locale per i test: **Example Connessione a DynamoDB locale** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import java.net.URI; DynamoDbClient dynamoDb = DynamoDbClient.builder() .endpointOverride(URI.create("http://localhost:8000")) // The region is meaningless for DynamoDB local but required for the client builder. .region(Region.US_WEST_2) .build(); ``` DynamoDB supporta anche l'uso [di endpoint basati su account](https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html), che possono essere configurati in codice o utilizzando impostazioni esterne. *L'esempio seguente mostra come disabilitare l'uso degli endpoint basati su account nel codice quando si crea il client (sono preferite le impostazioni predefinite):* ``` DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .region(Region.US_EAST_1) .accountIdEndpointMode(AccountIdEndpointMode.DISABLED) .build(); ``` ## Best practice Quando configuri gli endpoint in AWS SDK for Java 2.x, considera queste best practice: + *Utilizza la configurazione esterna per endpoint specifici dell'ambiente*: utilizza le variabili di ambiente, le proprietà del sistema o il file di AWS configurazione per gli endpoint che variano tra gli ambienti (sviluppo, test, produzione). + *Usa la configurazione in-code per endpoint specifici dell'applicazione: utilizza il metodo del client builder per endpoint* specifici per la progettazione dell'`endpointOverride`applicazione. + *Specificate sempre una regione*: anche quando sovrascrivete gli endpoint, specificate sempre una regione così come viene utilizzata per la firma delle richieste. + *Fai attenzione alle sostituzioni globali degli endpoint: l'utilizzo di sostituzioni globali degli* endpoint può influire su tutti i servizi, il che potrebbe non essere quello che intendi. + *Considerate le implicazioni per la sicurezza*: quando utilizzate endpoint personalizzati, assicuratevi che dispongano di misure di sicurezza appropriate, in particolare per i carichi di lavoro di produzione. # Configurare i client HTTP in AWS SDK for Java 2.x È possibile modificare il client HTTP da utilizzare per il client di servizio e modificare la configurazione predefinita per i client HTTP con AWS SDK for Java 2.x. Questa sezione illustra i client e le impostazioni HTTP per l'SDK. ## Client HTTP disponibili nell'SDK for Java ### Client sincroni I client HTTP sincroni nell'SDK for Java implementano [SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)l'interfaccia. Un client di servizio sincrono, come il `S3Client` o il`DynamoDbClient`, richiede l'uso di un client HTTP sincrono. AWS SDK per Java Offre tre client HTTP sincroni. **ApacheHttpClient (impostazione predefinita)** [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)è il client HTTP predefinito per i client di servizi sincroni. Per informazioni sulla configurazione di`ApacheHttpClient`, vedere. [Configurare il client HTTP basato su Apache](http-configuration-apache.md) **AwsCrtHttpClient** [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html)fornisce un throughput elevato e un IO non bloccante. È basato sul client Http AWS Common Runtime (CRT). Per informazioni sulla configurazione `AwsCrtHttpClient` e sul suo utilizzo con i client di servizio, vedere. [Configurazione AWS dei client HTTP basati su CRT](http-configuration-crt.md) **UrlConnectionHttpClient** Per ridurre al minimo il numero di jar e librerie di terze parti utilizzate dall'applicazione, è possibile utilizzare il. [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) Per informazioni sulla configurazione di`UrlConnectionHttpClient`, vedere. [Configurare il client HTTP URLConnection basato](http-configuration-url.md) **Apache 5 HttpClient** [Apache5 HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) *è una versione aggiornata basata su `ApacheHttpClient` Apache 5.x. HttpClient La versione 5.x* è la versione gestita attivamente da Apache e migliora la versione precedente utilizzata `ApacheHttpClient` offrendo la compatibilità con l'ecosistema Java moderno, incluso il supporto dei thread virtuali per Java 21 e una maggiore flessibilità di registrazione tramite SLF4 J. che `Apache5HttpClient` sostituirà `ApacheHttpClient` come client sincrono predefinito in una versione futura dell'SDK for AWS Java 2.x. Ha un'API e caratteristiche identiche, che la rendono ideale come sostituto immediato. Per informazioni sulla configurazione di, vedere. `Apache5HttpClient` [Configurazione del client HTTP basato su Apache 5.x](http-configuration-apache5.md) ### Client asincroni I client HTTP asincroni nell'SDK for Java implementano l'interfaccia. [SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html) Un client di servizio asincrono, come il `S3AsyncClient` o il, richiede l'uso di un client HTTP `DynamoDbAsyncClient` asincrono. Offre AWS SDK per Java due client HTTP asincroni. **NettyNioAsyncHttpClient (impostazione predefinita)** [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)è il client HTTP predefinito utilizzato dai client asincroni. Per informazioni sulla configurazione di, vedere. `NettyNioAsyncHttpClient` [Configurazione del client HTTP basato su Netty](http-configuration-netty.md) **AwsCrtAsyncHttpClient** [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)Si basa sul client HTTP AWS Common Runtime (CRT). Per informazioni sulla configurazione di`AwsCrtAsyncHttpClient`, vedere. [Configurazione AWS dei client HTTP basati su CRT](http-configuration-crt.md) ## Raccomandazioni sui client HTTP Quando si sceglie un'implementazione del client HTTP entrano in gioco diversi fattori. Utilizza le seguenti informazioni per aiutarti a decidere. ### diagramma di flusso dei consigli Il seguente diagramma di flusso fornisce indicazioni generali per aiutarti a determinare quale client HTTP utilizzare. ![\[Diagramma di flusso dei consigli sui client HTTP.\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/images/JavaDevGuide-HTTPflowchart-DI.png) ### Confronto tra client HTTP La tabella seguente fornisce informazioni dettagliate per ogni client HTTP. | Client HTTP | Sincronizzazione o asincrono | Quando utilizzare | Limitazione/inconveniente | | --- | --- | --- | --- | | Client HTTP basato su Apache *(client HTTP di sincronizzazione predefinito)* | Sync | Usalo se preferisci una bassa latenza rispetto a un throughput elevato | Tempo di avvio più lento rispetto ad altri client HTTP | | Client HTTP basato su URLConnection | Sync | Usalo se hai una forte esigenza di limitare le dipendenze di terze parti | Non supporta il metodo HTTP PATCH, richiesto da alcune API come le operazioni di Amazon APIGateway Update | | AWS Client HTTP di sincronizzazione basato su CRT 1 | Sync | • Usalo se l'applicazione è in esecuzione in AWS Lambda • Usalo se preferisci un throughput elevato rispetto a una bassa latenza • Usalo se preferisci sincronizzare i client SDK | Le seguenti proprietà del sistema Java non sono supportate: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/http-configuration.html) | | Client HTTP basato su Netty *(client HTTP asincrono predefinito)* | Asincrono | • Usalo se l'applicazione richiama richiami APIs che richiedono il supporto HTTP/2 come l'API Kinesis [SubscribeToShard](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_SubscribeToShard.html) | Tempo di avvio più lento rispetto ad altri client HTTP | | AWS Client HTTP asincrono basato su CRT 1 | Asincrono | • Usalo se l'applicazione è in esecuzione in AWS Lambda• Usalo se preferisci un throughput elevato rispetto a una bassa latenza• Usalo se preferisci i client SDK asincroni | • Non supporta client di servizio che richiedono il supporto HTTP/2 come e `KinesisAsynClient` `TranscribeStreamingAsyncClient` Le seguenti proprietà del sistema Java non sono supportate: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/http-configuration.html) | 1 A causa dei loro vantaggi aggiuntivi, si consiglia di utilizzare i client HTTP AWS basati su CRT, se possibile. ## Impostazioni predefinite di configurazione intelligente La AWS SDK for Java 2.x (versione 2.17.102 o successiva) offre una funzionalità di configurazione predefinita intelligente. Questa funzionalità ottimizza due proprietà del client HTTP insieme ad altre proprietà che non influiscono sul client HTTP. Le impostazioni predefinite di configurazione intelligente impostano valori ragionevoli per le `tlsNegotiationTimeoutInMillis` proprietà `connectTimeoutInMillis` and in base a un valore della modalità defaults fornito dall'utente. Scegliete il valore della modalità predefinita in base alle caratteristiche dell'applicazione. [Per ulteriori informazioni sulle impostazioni predefinite di configurazione intelligente e su come scegliere il valore della modalità predefinita più adatto alle applicazioni, consulta la and Tools Reference Guide.AWS SDKs ](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html) Di seguito sono riportati quattro modi per impostare la modalità predefinita per l'applicazione. ------ #### [ Service client ] Utilizzate il service client builder per configurare la modalità predefinita direttamente sul client del servizio. L'esempio seguente imposta la modalità predefinita su. `auto` `DynamoDbClient` ``` DynamoDbClient ddbClient = DynamoDbClient.builder() .defaultsMode(DefaultsMode.AUTO) .build(); ``` ------ #### [ System property ] È possibile utilizzare la proprietà `aws.defaultsMode` di sistema per specificare la modalità predefinita. Se si imposta la proprietà di sistema in Java, è necessario impostare la proprietà prima di inizializzare qualsiasi client di servizio. L'esempio seguente mostra come impostare la modalità di default sull'`auto`utilizzo di una proprietà di sistema impostata in Java. ``` System.setProperty("aws.defaultsMode", "auto"); ``` L'esempio seguente mostra come impostare la modalità di default per l'`auto`utilizzo di un'`-D`opzione del comando. `java` ``` java -Daws.defaultsMode=auto ``` ------ #### [ Environment variable ] Imposta un valore per la variabile di ambiente `AWS_DEFAULTS_MODE` per selezionare la modalità predefinita per l'applicazione. Le informazioni seguenti mostrano il comando da eseguire per impostare il valore della modalità predefinita sull'`auto`utilizzo di una variabile di ambiente. | Sistema operativo | Comando per impostare le variabili di ambiente | | --- | --- | | Linux, macOS o Unix | export AWS\$1DEFAULTS\$1MODE=auto | | Windows | set AWS\$1DEFAULTS\$1MODE=auto | ------ #### [ AWS config file ] È possibile aggiungere una proprietà di `defaults_mode` configurazione al AWS `config` file condiviso come illustrato nell'esempio seguente. ``` [default] defaults_mode = auto ``` ------ Se impostate la modalità predefinita a livello globale con la proprietà di sistema, la variabile di ambiente o il file di AWS configurazione, potete sovrascrivere le impostazioni quando create un client HTTP. Quando create un client HTTP con il `httpClientBuilder()` metodo, le impostazioni si applicano solo all'istanza che state creando. Un esempio di ciò è mostrato [qui](http-configuration-netty.md#http-config-netty-one-client). Il client HTTP basato su Netty in questo esempio sostituisce tutti i valori di modalità predefiniti impostati globalmente per and. `connectTimeoutInMillis` `tlsNegotiationTimeoutInMillis` # Configurare il client HTTP basato su Apache Per impostazione predefinita, i client di servizio sincroni AWS SDK for Java 2.x utilizzano un client HTTP basato su Apache. [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) L'SDK è basato su `ApacheHttpClient` Apache. [HttpClient](https://hc.apache.org/httpcomponents-client-4.5.x/index.html) L'SDK offre anche il [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html), che si carica più rapidamente, ma ha meno funzionalità. Per informazioni sulla configurazione di`UrlConnectionHttpClient`, consulta. [Configurare il client HTTP URLConnection basato](http-configuration-url.md) [Per visualizzare il set completo di opzioni di configurazione disponibili per`ApacheHttpClient`, consulta [ApacheHttpClient.Builder e .Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html). ProxyConfiguration](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html) ## Accedi a `ApacheHttpClient` Nella maggior parte dei casi, si utilizza `ApacheHttpClient` senza alcuna configurazione esplicita. Dichiari i tuoi client di servizio e l'SDK li configurerà automaticamente `ApacheHttpClient` con valori standard. Se desideri configurarlo in modo esplicito `ApacheHttpClient` o utilizzarlo con più client di servizio, devi renderlo disponibile per la configurazione. ### Non è necessaria alcuna configurazione Quando si dichiara una dipendenza da un client di servizio in Maven, l'SDK aggiunge una dipendenza di *runtime* dall'artefatto. `apache-client` Ciò rende la `ApacheHttpClient` classe disponibile per il codice in fase di esecuzione, ma non in fase di compilazione. Se non state configurando il client HTTP basato su Apache, non è necessario specificare una dipendenza per esso. Nel seguente frammento XML di un `pom.xml` file Maven, la dipendenza dichiarata con introduce automaticamente il client HTTP basato su Apache. `s3` Non è necessario dichiarare una dipendenza specifica per questo. ``` software.amazon.awssdk bom 2.27.21 pom import software.amazon.awssdk s3 ``` Con queste dipendenze, non è possibile apportare modifiche esplicite alla configurazione HTTP, poiché la `ApacheHttpClient` libreria si trova solo nel classpath di runtime. ### Configurazione necessaria *Per configurare`ApacheHttpClient`, è necessario aggiungere una dipendenza dalla libreria in fase di compilazione`apache-client`.* Fate riferimento al seguente esempio di `pom.xml` file Maven per configurare. `ApacheHttpClient` ``` software.amazon.awssdk bom 2.27.21 pom import software.amazon.awssdk s3 software.amazon.awssdk apache-client ``` ## Usa e configura il `ApacheHttpClient` È possibile configurare un'istanza `ApacheHttpClient` insieme alla creazione di un client di servizio oppure configurare una singola istanza da condividere tra più client di servizio. Con entrambi gli approcci, si utilizza `[ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html)` per configurare le proprietà per il client HTTP basato su Apache. ### Procedura consigliata: dedicare un'`ApacheHttpClient`istanza a un client di servizio Se devi configurare un'istanza di`ApacheHttpClient`, ti consigliamo di creare l'`ApacheHttpClient`istanza dedicata. Puoi farlo utilizzando il `httpClientBuilder` metodo del builder del client del servizio. In questo modo, il ciclo di vita del client HTTP viene gestito dall'SDK, che aiuta a evitare potenziali perdite di memoria se l'`ApacheHttpClient`istanza non viene chiusa quando non è più necessaria. L'esempio seguente crea `S3Client` e configura l'istanza incorporata di with and values. `ApacheHttpClient` `maxConnections` `connectionTimeout` L'istanza HTTP viene creata utilizzando il `httpClientBuilder` metodo di`S3Client.Builder`. **Importazioni** ``` import software.amazon.awssdk.http.apache.ApacheHttpClient; import software.amazon.awssdk.services.s3.S3Client; import java.time.Duration; ``` **Codice** ``` S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests. .builder() .httpClientBuilder(ApacheHttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) ).build(); // Perform work with the s3Client. s3Client.close(); // Requests completed: Close all service clients. ``` ### Approccio alternativo: condividere un'`ApacheHttpClient`istanza Per ridurre l'utilizzo di risorse e memoria per l'applicazione, è possibile configurarne un'applicazione `ApacheHttpClient` e condividerla tra più client di servizio. Il pool di connessioni HTTP verrà condiviso, il che riduce l'utilizzo delle risorse. **Nota** Quando un'`ApacheHttpClient`istanza è condivisa, è necessario chiuderla quando è pronta per essere eliminata. L'SDK non chiuderà l'istanza quando il client del servizio viene chiuso. L'esempio seguente configura un client HTTP basato su Apache utilizzato da due client di servizio. L'`ApacheHttpClient`istanza configurata viene passata al `httpClient` metodo di ogni builder. Quando i client di servizio e il client HTTP non sono più necessari, il codice li chiude esplicitamente. Il codice chiude per ultimo il client HTTP. **Importazioni** ``` import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.apache.ApacheHttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.s3.S3Client; ``` **Codice** ``` SdkHttpClient apacheHttpClient = ApacheHttpClient.builder() .maxConnections(100).build(); // Singletons: Use the s3Client and dynamoDbClient for all requests. S3Client s3Client = S3Client.builder() .httpClient(apacheHttpClient).build(); DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(apacheHttpClient).build(); // Perform work with the s3Client and dynamoDbClient. // Requests completed: Close all service clients. s3Client.close(); dynamoDbClient.close(); apacheHttpClient.close(); // Explicitly close apacheHttpClient. ``` ## Esempio di configurazione del proxy Il seguente frammento di codice utilizza il [generatore di configurazione proxy per il client HTTP Apache](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html). ``` SdkHttpClient apacheHttpClient = ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://example.com:1234")) .username("username") .password("password") .addNonProxyHost("localhost") .addNonProxyHost("host.example.com") .build()) .build(); ``` Le proprietà di sistema Java equivalenti per la configurazione del proxy sono mostrate nel seguente frammento di riga di comando. ``` $ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \ -Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App ``` La configurazione equivalente che utilizza le variabili di ambiente è: ``` // Set the following environment variables. // $ export HTTP_PROXY="http://username:password@example.com:1234" // $ export NO_PROXY="localhost|host.example.com" // Set the 'useSystemPropertyValues' to false on the proxy configuration. SdkHttpClient apacheHttpClient = ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .useSystemPropertyValues(Boolean.FALSE) .build()) .build(); // Run the application. // $ java -cp ... App ``` **Nota** Il client HTTP Apache attualmente non supporta le proprietà del sistema proxy HTTPS o la variabile di ambiente HTTPS\$1PROXY. # Configurare il client HTTP URLConnection basato AWS SDK for Java 2.x Offre un client `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)` HTTP più leggero rispetto a quello predefinito. `ApacheHttpClient` `UrlConnectionHttpClient`È basato su Java. `[URLConnection](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/URLConnection.html)` Si `UrlConnectionHttpClient` carica più rapidamente rispetto al client HTTP basato su Apache, ma ha meno funzionalità. Poiché si carica più rapidamente, è una [buona soluzione](lambda-optimize-starttime.md) per le funzioni Java. AWS Lambda `UrlConnectionHttpClient`Ha diverse [opzioni configurabili](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html) a cui puoi accedere. **Nota** Non `UrlConnectionHttpClient` supporta il metodo HTTP PATCH. Alcune operazioni AWS API richiedono richieste PATCH. I nomi di queste operazioni di solito iniziano con`Update*`. Di seguito sono riportati alcuni esempi. [Diverse `Update*` operazioni](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Operations.html) nell' AWS Security Hub CSPM API e anche l'[BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html)operazione Tutte le [`Update*`operazioni](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html) API di Amazon API Gateway Se puoi utilizzare il`UrlConnectionHttpClient`, consulta innanzitutto l'API Reference relativo a Servizio AWS quello che stai utilizzando. Verifica se le operazioni necessarie utilizzano l'operazione PATCH. ## Accedi al `UrlConnectionHttpClient` Per configurare e utilizzare`UrlConnectionHttpClient`, dichiari una dipendenza dall'artefatto `url-connection-client` Maven nel tuo file. `pom.xml` A differenza di`ApacheHttpClient`, non `UrlConnectionHttpClient` viene aggiunto automaticamente al progetto, quindi use deve dichiararlo specificamente. Il seguente esempio di `pom.xml` file mostra le dipendenze necessarie per utilizzare e configurare il client HTTP. ``` software.amazon.awssdk bom 2.27.21 pom import software.amazon.awssdk url-connection-client ``` ## Usa e configura il `UrlConnectionHttpClient` È possibile configurare un'istanza `UrlConnectionHttpClient` insieme alla creazione di un client di servizio oppure configurare una singola istanza da condividere tra più client di servizio. Con entrambi gli approcci, si utilizza [UrlConnectionHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html) per configurare le proprietà per il client HTTP URLConnection basato. ### Procedura consigliata: dedicare un'`UrlConnectionHttpClient`istanza a un client di servizio Se devi configurare un'istanza di`UrlConnectionHttpClient`, ti consigliamo di creare l'`UrlConnectionHttpClient`istanza dedicata. Puoi farlo utilizzando il `httpClientBuilder` metodo del builder del client del servizio. In questo modo, il ciclo di vita del client HTTP viene gestito dall'SDK, che aiuta a evitare potenziali perdite di memoria se l'`UrlConnectionHttpClient`istanza non viene chiusa quando non è più necessaria. L'esempio seguente crea `S3Client` e configura l'istanza incorporata di with and values. `UrlConnectionHttpClient` `socketTimeout` `proxyConfiguration` Il `proxyConfiguration` metodo accetta un'espressione lambda Java di tipo. ` Consumer<[ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)>` **Importazioni** ``` import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient; import java.net.URI; import java.time.Duration; ``` **Codice** ``` // Singleton: Use the s3Client for all requests. S3Client s3Client = S3Client.builder() .httpClientBuilder(UrlConnectionHttpClient.builder() .socketTimeout(Duration.ofMinutes(5)) .proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.mydomain.net:8888")))) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build(); // Perform work with the s3Client. s3Client.close(); // Requests completed: Close the s3client. ``` ### Approccio alternativo: condividi un'istanza `UrlConnectionHttpClient` Per ridurre l'utilizzo di risorse e memoria per l'applicazione, è possibile configurarne un'applicazione `UrlConnectionHttpClient` e condividerla tra più client di servizio. Il pool di connessioni HTTP verrà condiviso, il che riduce l'utilizzo delle risorse. **Nota** Quando un'`UrlConnectionHttpClient`istanza è condivisa, è necessario chiuderla quando è pronta per essere eliminata. L'SDK non chiuderà l'istanza quando il client del servizio viene chiuso. L'esempio seguente configura un client HTTP URLConnection basato che viene utilizzato da due client di servizio. L'`UrlConnectionHttpClient`istanza configurata viene passata al `httpClient` metodo di ogni builder. Quando i client di servizio e il client HTTP non sono più necessari, il codice li chiude esplicitamente. Il codice chiude per ultimo il client HTTP. **Importazioni** ``` import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider; import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode; import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.urlconnection.ProxyConfiguration; import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.s3.S3Client; import java.net.URI; import java.time.Duration; ``` **Codice** ``` SdkHttpClient urlHttpClient = UrlConnectionHttpClient.create(); // Singletons: Use the s3Client and dynamoDbClient for all requests. S3Client s3Client = S3Client.builder() .httpClient(urlHttpClient) .defaultsMode(DefaultsMode.IN_REGION) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build(); DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(urlHttpClient) .defaultsMode(DefaultsMode.IN_REGION) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build(); // Perform work with the s3Client and dynamoDbClient. // Requests completed: Close all service clients. s3Client.close(); dynamoDbClient.close(); urlHttpClient.close(); ``` #### Usa `URLConnectionHttpClient` e insieme `ApacheHttpClient` Quando si utilizza il `UrlConnectionHttpClient` nella propria applicazione, è necessario fornire a ciascun client di servizio un'`URLConnectionHttpClient`istanza o un'`ApacheHttpClient`istanza utilizzando il `httpClientBuilder` metodo del service client builder. Si verifica un'eccezione se il programma utilizza più client di servizio ed entrambe le seguenti condizioni sono vere: + Un client di servizio è configurato per utilizzare un'`UrlConnectionHttpClient`istanza + Un altro client di servizio utilizza l'impostazione predefinita `ApacheHttpClient` senza crearla esplicitamente con i metodi `httpClient()` o `httpClientBuilder()` L'eccezione indicherà che nel classpath sono state trovate più implementazioni HTTP. Il seguente frammento di codice di esempio porta a un'eccezione. ``` // The dynamoDbClient uses the UrlConnectionHttpClient DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(UrlConnectionHttpClient.create()) .build(); // The s3Client below uses the ApacheHttpClient at runtime, without specifying it. // An SdkClientException is thrown with the message that multiple HTTP implementations were found on the classpath. S3Client s3Client = S3Client.create(); // Perform work with the s3Client and dynamoDbClient. dynamoDbClient.close(); s3Client.close(); ``` Evita l'eccezione configurando esplicitamente il con un. `S3Client` `ApacheHttpClient` ``` DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(UrlConnectionHttpClient.create()) .build(); S3Client s3Client = S3Client.builder() .httpClient(ApacheHttpClient.create()) // Explicitly build the ApacheHttpClient. .build(); // Perform work with the s3Client and dynamoDbClient. dynamoDbClient.close(); s3Client.close(); ``` **Nota** Per creare esplicitamente il`ApacheHttpClient`, è necessario [aggiungere una dipendenza dall'](http-configuration-apache.md#http-apache-dependency)`apache-client`artefatto nel file di progetto Maven. ## Esempio di configurazione del proxy Il seguente frammento di codice utilizza il [generatore di configurazione proxy per il client HTTP di connessione URL.](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html) ``` SdkHttpClient urlHttpClient = UrlConnectionHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://example.com:1234")) .username("username") .password("password") .addNonProxyHost("localhost") .addNonProxyHost("host.example.com") .build()) .build(); ``` Le proprietà di sistema Java equivalenti per la configurazione del proxy sono mostrate nel seguente frammento di riga di comando. ``` $ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \ -Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App ``` La configurazione equivalente che utilizza le variabili di ambiente è: ``` // Set the following environment variables. // $ export HTTP_PROXY="http://username:password@example.com:1234" // $ export NO_PROXY="localhost|host.example.com" // Set the 'useSystemPropertyValues' to false on the proxy configuration. SdkHttpClient apacheHttpClient = UrlConnectionHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .useSystemPropertyValues(Boolean.FALSE) .build()) .build(); // Run the application. // $ java -cp ... App ``` **Nota** Il client HTTP URLConnection basato attualmente non supporta le proprietà del sistema proxy HTTPS o la variabile di ambiente HTTPS\$1PROXY. # Configurazione del client HTTP basato su Netty Il client HTTP predefinito per le operazioni asincrone in è basato su Netty. AWS SDK for Java 2.x [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) [Il client basato su Netty si basa sul framework di rete asincrono basato sugli eventi del progetto Netty.](https://netty.io/) [Come client HTTP alternativo, è possibile utilizzare il nuovo client HTTP basato su CRT.AWS](http-configuration-crt.md) In questo argomento viene illustrato come configurare. `NettyNioAsyncHttpClient` ## Accedere a `NettyNioAsyncHttpClient` Nella maggior parte dei casi, si utilizza la `NettyNioAsyncHttpClient` senza alcuna configurazione esplicita nei programmi asincroni. Dichiari i tuoi client di servizio asincroni e l'SDK li configurerà automaticamente con valori standard. `NettyNioAsyncHttpClient` Se desideri configurarli in modo esplicito `NettyNioAsyncHttpClient` o utilizzarli con più client di servizio, devi renderli disponibili per la configurazione. ### Non è necessaria alcuna configurazione Quando si dichiara una dipendenza da un client di servizio in Maven, l'SDK aggiunge una dipendenza di *runtime* dall'artefatto. `netty-nio-client` Ciò rende la `NettyNioAsyncHttpClient` classe disponibile per il codice in fase di esecuzione, ma non in fase di compilazione. Se non state configurando il client HTTP basato su Netty, non è necessario specificare una dipendenza per esso. Nel seguente frammento XML di un `pom.xml` file Maven, la dipendenza dichiarata con richiama in modo transitivo il client HTTP basato su Netty. `dynamodb-enhanced` Non è necessario dichiarare una dipendenza specifica per questo. ``` software.amazon.awssdk bom 2.27.21 pom import software.amazon.awssdk dynamodb-enhanced ``` Con queste dipendenze, non è possibile apportare modifiche alla configurazione HTTP, poiché la `NettyNioAsyncHttpClient` libreria si trova solo nel classpath di runtime. ### Configurazione necessaria *Per configurare`NettyNioAsyncHttpClient`, è necessario aggiungere una dipendenza dall'`netty-nio-client`artefatto in fase di compilazione.* Fate riferimento al seguente esempio di file `pom.xml` Maven per configurare. `NettyNioAsyncHttpClient` ``` software.amazon.awssdk bom 2.27.21 pom import software.amazon.awssdk dynamodb-enhanced software.amazon.awssdk netty-nio-client ``` ## Usa e configura il `NettyNioAsyncHttpClient` È possibile configurare un'istanza `NettyNioAsyncHttpClient` insieme alla creazione di un client di servizio oppure configurare una singola istanza da condividere tra più client di servizio. Con entrambi gli approcci, si utilizza [NettyNioAsyncHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html) per configurare le proprietà per l'istanza del client HTTP basata su Netty. ### Procedura consigliata: dedicare un'`NettyNioAsyncHttpClient`istanza a un client di servizio Se devi configurare un'istanza di`NettyNioAsyncHttpClient`, ti consigliamo di creare un'`NettyNioAsyncHttpClient`istanza dedicata. Puoi farlo utilizzando il `httpClientBuilder` metodo del builder del client del servizio. In questo modo, il ciclo di vita del client HTTP viene gestito dall'SDK, che aiuta a evitare potenziali perdite di memoria se l'`NettyNioAsyncHttpClient`istanza non viene chiusa quando non è più necessaria. L'esempio seguente crea un'`DynamoDbAsyncClient`istanza che viene utilizzata da un'istanza. `DynamoDbEnhancedAsyncClient` L'`DynamoDbAsyncClient`istanza contiene l'`NettyNioAsyncHttpClient`istanza con `connectionTimeout` e `maxConcurrency` valori. L'istanza HTTP viene creata utilizzando `httpClientBuilder` il metodo di`DynamoDbAsyncClient.Builder`. **Importazioni** ``` import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider; import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode; import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient; import software.amazon.awssdk.enhanced.dynamodb.extensions.AutoGeneratedTimestampRecordExtension; import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient; import java.time.Duration; ``` **Codice** ``` // DynamoDbAsyncClient is the lower-level client used by the enhanced client. DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient .builder() .httpClientBuilder(NettyNioAsyncHttpClient.builder() .connectionTimeout(Duration.ofMillis(5_000)) .maxConcurrency(100) .tlsNegotiationTimeout(Duration.ofMillis(3_500))) .defaultsMode(DefaultsMode.IN_REGION) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build(); // Singleton: Use dynamoDbAsyncClient and enhancedClient for all requests. DynamoDbEnhancedAsyncClient enhancedClient = DynamoDbEnhancedAsyncClient .builder() .dynamoDbClient(dynamoDbAsyncClient) .extensions(AutoGeneratedTimestampRecordExtension.create()) .build(); // Perform work with the dynamoDbAsyncClient and enhancedClient. // Requests completed: Close dynamoDbAsyncClient. dynamoDbAsyncClient.close(); ``` ### Approccio alternativo: condividi un'`NettyNioAsyncHttpClient`istanza Per ridurre l'utilizzo di risorse e memoria per l'applicazione, è possibile configurare un'applicazione `NettyNioAsyncHttpClient` e condividerla tra più client di servizio. Il pool di connessioni HTTP verrà condiviso, il che riduce l'utilizzo delle risorse. **Nota** Quando un'`NettyNioAsyncHttpClient`istanza è condivisa, è necessario chiuderla quando è pronta per essere eliminata. L'SDK non chiuderà l'istanza quando il client del servizio viene chiuso. L'esempio seguente configura un client HTTP basato su Netty utilizzato da due client di servizio. L'`NettyNioAsyncHttpClient`istanza configurata viene passata al `httpClient` metodo di ogni builder. Quando i client di servizio e il client HTTP non sono più necessari, il codice li chiude esplicitamente. Il codice chiude per ultimo il client HTTP. **Importazioni** ``` import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.apache.ApacheHttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.s3.S3Client; ``` **Codice** ``` // Create a NettyNioAsyncHttpClient shared instance. SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder().maxConcurrency(100).build(); // Singletons: Use the s3AsyncClient, dbAsyncClient, and enhancedAsyncClient for all requests. S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .httpClient(nettyHttpClient) .build(); DynamoDbAsyncClient dbAsyncClient = DynamoDbAsyncClient.builder() .httpClient(nettyHttpClient) .defaultsMode(DefaultsMode.IN_REGION) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build(); DynamoDbEnhancedAsyncClient enhancedAsyncClient = DynamoDbEnhancedAsyncClient.builder() .dynamoDbClient(dbAsyncClient) .extensions(AutoGeneratedTimestampRecordExtension.create()) .build(); // Perform work with s3AsyncClient, dbAsyncClient, and enhancedAsyncClient. // Requests completed: Close all service clients. s3AsyncClient.close(); dbAsyncClient.close() nettyHttpClient.close(); // Explicitly close nettyHttpClient. ``` ## Configura la negoziazione del protocollo ALPN ALPN (Application-Layer Protocol Negotiation) è un'estensione TLS che consente al livello dell'applicazione di negoziare quale protocollo deve essere eseguito su una connessione sicura in modo da evitare ulteriori round trip e offrire prestazioni migliori. Per consentire al client HTTP basato su Netty di utilizzare ALPN, chiamate i metodi builder come illustrato nel seguente frammento: ``` import software.amazon.awssdk.http.Protocol; import software.amazon.awssdk.http.ProtocolNegotiation; import software.amazon.awssdk.http.async.SdkAsyncHttpClient; import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient; import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient; // Configure the Netty-based HTTP client to use the ALPN protocol. SdkAsyncHttpClient nettyClient = NettyNioAsyncHttpClient.builder() .protocol(Protocol.HTTP2) .protocolNegotiation(ProtocolNegotiation.ALPN) .build(); // Use the Netty-based HTTP client with a service client. TranscribeStreamingAsyncClient transcribeClient = TranscribeStreamingAsyncClient.builder() .httpClient(nettyClient) .build(); ``` La negoziazione del protocollo ALPN attualmente funziona solo con il protocollo HTTP/2, come mostrato nello snippet precedente. ## Esempio di configurazione del proxy Il seguente frammento di codice utilizza il [generatore di configurazione proxy per il client HTTP Netty](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/ProxyConfiguration.Builder.html). ``` SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .scheme("https") .host("myproxy") .port(1234) .username("username") .password("password") .nonProxyHosts(Set.of("localhost", "host.example.com")) .build()) .build(); ``` Le proprietà di sistema Java equivalenti per la configurazione del proxy sono mostrate nel seguente frammento di riga di comando. ``` $ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \ -Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App ``` **Importante** Per utilizzare una qualsiasi delle proprietà del sistema proxy HTTPS, la `scheme` proprietà deve essere impostata nel codice su. `https` Se la proprietà scheme non è impostata nel codice, per impostazione predefinita lo schema è HTTP e l'SDK cerca `http.*` solo le proprietà di sistema. La configurazione equivalente che utilizza le variabili di ambiente è: ``` // Set the following environment variables. // $ export HTTPS_PROXY="https://username:password@myproxy:1234" // $ export NO_PROXY="localhost|host.example.com" // Set the 'useSystemPropertyValues' to false on the proxy configuration. SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .useSystemPropertyValues(Boolean.FALSE) .build()) .build(); // Run the application. // $ java -cp ... App ``` # Configurazione AWS dei client HTTP basati su CRT I client HTTP AWS basati su CRT includono quelli sincroni e asincroni. [AwsCrtHttpClient[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) I client HTTP AWS basati su CRT offrono i seguenti vantaggi del client HTTP: + Tempo di avvio del’SDK più rapido + Ingombro di memoria minore + Tempo di latenza ridotto + Gestione dell’integrità delle connessioni + Bilanciamento del carico DNS **AWS Componenti basati su CRT nell'SDK** I client *HTTP AWS * basati su CRT, descritti in questo argomento, e il client *S3 AWS basato su CRT sono componenti diversi dell'SDK*. I client HTTP sincroni e asincroni **AWS basati su CRT sono interfacce client HTTP SDK di implementazione e vengono utilizzati per comunicazioni HTTP** generali. Sono alternative agli altri client HTTP sincroni o asincroni dell'SDK con vantaggi aggiuntivi. Il **[client S3 AWS basato su CRT](crt-based-s3-client.md)** è un'implementazione dell'AsyncClientinterfaccia [S3](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) e viene utilizzato per lavorare con il servizio Amazon S3. È un'alternativa all'implementazione dell'interfaccia basata su Java e offre diversi vantaggi. `S3AsyncClient` Sebbene entrambi i componenti utilizzino librerie del [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html), i client HTTP AWS basati su CRT non utilizzano la [libreria aws-c-s 3](https://github.com/awslabs/aws-c-s3) e non supportano le funzionalità dell'API di caricamento multipart di [S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html). Il client S3 AWS basato su CRT, invece, è stato creato appositamente per supportare le funzionalità dell'API di caricamento multiparte di S3. ## Accedi AWS ai client HTTP basati su CRT Prima di poter utilizzare i client HTTP AWS basati su CRT, aggiungete l'`aws-crt-client`artefatto con una versione minima di 2.22.0 alle dipendenze del progetto. Usa una delle seguenti opzioni per configurare il tuo file Maven. `pom.xml` **Nota** È possibile scegliere di utilizzare l'*opzione jar specifica della piattaforma* se è necessario ridurre le dimensioni delle dipendenze di runtime, ad esempio se l'applicazione viene eseguita in una funzione. AWS Lambda ------ #### [ Uber-jar option ] Per impostazione predefinita, `aws-crt-client` utilizza un uber-jar di artefatti AWS CRT che contiene file binari per diverse piattaforme, tra cui Linux, Windows e macOS. ``` 2.29.10* software.amazon.awssdk bom ${aws.sdk.version} pom import software.amazon.awssdk aws-crt-client ``` \$1Sostituisci la versione mostrata in rosso con la versione di Java SDK che desideri utilizzare. Trova le ultime novità su [Maven](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) Central. ------ #### [ Platform-specific jar option ] *Per limitare il runtime Java alla versione specifica della piattaforma della libreria AWS CRT, apporta le seguenti modifiche all'opzione Uber-JAR.* + Aggiungi un `exclusions` elemento all'artefatto dell'SDK. `aws-crt-client` Questa esclusione impedisce all'SDK di utilizzare transitivamente il CRT uber-jar. AWS + Aggiungi un elemento di dipendenza per la versione specifica della piattaforma CRT di cui hai bisogno. AWS **Consultate i passaggi per determinare la versione dell'artefatto AWS CRT di seguito per sapere come determinare la versione** corretta. ``` 2.29.101 software.amazon.awssdk bom ${aws.sdk.java.version} pom import software.amazon.awssdk aws-crt-client software.amazon.awssdk.crt aws-crt software.amazon.awssdk.crt aws-crt 0.31.32 linux-x86_643 ``` 1 Sostituisci la versione mostrata in rosso con la versione di Java SDK che desideri utilizzare. Trova le ultime novità su [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom). 2 Sostituisci la versione `software.amazon.awssdk.crt:aws-crt` che sarebbe fornita dall'opzione *Uber-JAR*. Vedi i seguenti **passaggi per determinare la versione dell'artefatto AWS CRT**. 3 Sostituisci il `classifier` valore con uno per la tua piattaforma. Fate riferimento alla GitHub pagina AWS CRT per Java per un [elenco dei valori disponibili](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars). **Passaggi per determinare la versione dell' AWS artefatto CRT** Utilizzate i seguenti passaggi per determinare la versione dell'artefatto AWS CRT compatibile con la versione dell'SDK for Java in uso. 1. *Configura il `pom.xml` file come mostrato nell'opzione Uber-JAR.* Questa configurazione ti consente di vedere quale versione dell'SDK `software.amazon.awssdk.crt:aws-crt` è disponibile per impostazione predefinita. 1. Alla radice del progetto (nella stessa directory del `pom.xml` file), esegui il seguente comando Maven: ``` mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt ``` Maven potrebbe eseguire altre azioni, ma alla fine dovresti vedere l'output della console della `software.amazon.awssdk.crt:aws-crt` dipendenza utilizzata dall'SDK in modo transitivo. Il seguente frammento mostra un output di esempio basato su una versione SDK di: `2.29.10` ``` [INFO] org.example:yourProject:jar:1.0-SNAPSHOT [INFO] \- software.amazon.awssdk:aws-crt-client:jar:2.29.10:compile [INFO] \- software.amazon.awssdk.crt:aws-crt:jar:0.31.3:compile ``` 1. Usa la versione mostrata dalla console per l'artefatto. `software.amazon.awssdk.crt:aws-crt` In questo caso, aggiungilo `0.31.3` al tuo `pom.xml` file. ------ ## Usa e configura un client HTTP AWS basato su CRT È possibile configurare un client HTTP AWS basato su CRT insieme alla creazione di un client di servizio oppure è possibile configurare una singola istanza da condividere tra più client di servizio. Con entrambi gli approcci, si utilizza un builder per [configurare le proprietà per l'istanza del client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html) HTTP basato su AWS CRT. ### Procedura consigliata: dedicare un'istanza a un client di servizio Se devi configurare un'istanza di un client HTTP AWS basato su CRT, ti consigliamo di dedicare l'istanza costruendola insieme al client di servizio. Puoi farlo utilizzando il `httpClientBuilder` metodo del builder del client del servizio. In questo modo, il ciclo di vita del client HTTP viene gestito dall'SDK, che aiuta a evitare potenziali perdite di memoria se l'istanza del client HTTP AWS basato su CRT non viene chiusa quando non è più necessaria. L'esempio seguente crea un client di servizio S3 e configura un client HTTP basato su CRT con valori e. AWS `connectionTimeout` `maxConcurrency` ------ #### [ Synchronous client ] **Importazioni** ``` import software.amazon.awssdk.http.crt.AwsCrtHttpClient; import software.amazon.awssdk.services.s3.S3Client; import java.time.Duration; ``` **Codice** ``` // Singleton: Use s3Client for all requests. S3Client s3Client = S3Client.builder() .httpClientBuilder(AwsCrtHttpClient .builder() .connectionTimeout(Duration.ofSeconds(3)) .maxConcurrency(100)) .build(); // Perform work with the s3Client. // Requests completed: Close the s3Client. s3Client.close(); ``` ------ #### [ Asynchronous client ] **Importazioni** ``` import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient; import software.amazon.awssdk.services.s3.S3AsyncClient; import java.time.Duration; ``` **Codice** ``` // Singleton: Use s3AsyncClient for all requests. S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .httpClientBuilder(AwsCrtAsyncHttpClient .builder() .connectionTimeout(Duration.ofSeconds(3)) .maxConcurrency(100)) .build(); // Perform work with the s3AsyncClient. // Requests completed: Close the s3AsyncClient. s3AsyncClient.close(); ``` ------ ### Approccio alternativo: condividi un'istanza Per ridurre l'utilizzo di risorse e memoria per l'applicazione, è possibile configurare un client HTTP AWS basato su CRT e condividerlo tra più client di servizio. Il pool di connessioni HTTP verrà condiviso, il che riduce l'utilizzo delle risorse. **Nota** Quando un'istanza client HTTP AWS basata su CRT viene condivisa, è necessario chiuderla quando è pronta per essere eliminata. L'SDK non chiuderà l'istanza quando il client del servizio viene chiuso. L'esempio seguente configura un'istanza client HTTP AWS basata su CRT con valori e. `connectionTimeout` `maxConcurrency` L'istanza configurata viene passata al `httpClient` metodo del builder di ogni client di servizio. Quando i client di servizio e il client HTTP non sono più necessari, vengono chiusi in modo esplicito. Il client HTTP viene chiuso per ultimo. ------ #### [ Synchronous client ] **Importazioni** ``` import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider; import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode; import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.crt.AwsCrtHttpClient; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.s3.S3Client; import java.time.Duration; ``` **Codice** ``` // Create an AwsCrtHttpClient shared instance. SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder() .connectionTimeout(Duration.ofSeconds(3)) .maxConcurrency(100) .build(); // Singletons: Use the s3Client and dynamoDbClient for all requests. S3Client s3Client = S3Client.builder() .httpClient(crtHttpClient) .credentialsProvider(EnvironmentVariableCredentialsProvider.crea .defaultsMode(DefaultsMode.IN_REGION) .region(Region.US_EAST_1) .build(); DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(crtHttpClient) .credentialsProvider(EnvironmentVariableCredentialsProvider.crea .defaultsMode(DefaultsMode.IN_REGION) .region(Region.US_EAST_1) .build(); // Requests completed: Close all service clients. s3Client.close(); dynamoDbClient.close(); crtHttpClient.close(); // Explicitly close crtHttpClient. ``` ------ #### [ Asynchronous client ] **Importazioni** ``` import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider; import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode; import software.amazon.awssdk.http.async.SdkAsyncHttpClient; import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient; import software.amazon.awssdk.services.s3.S3AsyncClient; import java.time.Duration; ``` **Codice** ``` // Create an AwsCrtAsyncHttpClient shared instance. SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder() .connectionTimeout(Duration.ofSeconds(3)) .maxConcurrency(100) .build(); // Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests. S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .httpClient(crtAsyncHttpClient) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .defaultsMode(DefaultsMode.IN_REGION) .region(Region.US_EAST_1) .build(); DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder() .httpClient(crtAsyncHttpClient) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .defaultsMode(DefaultsMode.IN_REGION) .region(Region.US_EAST_1) .build(); // Requests completed: Close all service clients. s3AsyncClient.close(); dynamoDbAsyncClient.close(); crtAsyncHttpClient.close(); // Explicitly close crtAsyncHttpClient. ``` ------ ## Imposta un client HTTP AWS basato su CRT come predefinito Puoi configurare il tuo file di build Maven in modo che l'SDK utilizzi un client HTTP AWS basato su CRT come client HTTP predefinito per i client di servizio. A tale scopo, è possibile aggiungere un `exclusions` elemento con le dipendenze del client HTTP predefinite a ciascun elemento del client di servizio. Nell'`pom.xml`esempio seguente, l'SDK utilizza un client HTTP AWS basato su CRT per i servizi S3. Se il client di servizio nel codice è un`S3AsyncClient`, l'SDK lo utilizza. `AwsCrtAsyncHttpClient` Se il client di servizio è un S3Client, l'SDK utilizza. `AwsCrtHttpClient` Con questa configurazione il client HTTP asincrono predefinito basato su Netty e l'HTTP sincrono predefinito basato su Apache non sono disponibili. ``` VERSION software.amazon.awssdk s3 ${aws.sdk.version} software.amazon.awssdk netty-nio-client software.amazon.awssdk apache-client software.amazon.awssdk aws-crt-client ``` Visita il repository centrale di Maven per le ultime novità. [https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) **Nota** Se più client di servizio sono dichiarati in un `pom.xml` file, tutti richiedono l'`exclusions`elemento XML. ### Utilizzate una proprietà di sistema Java Per utilizzare i client HTTP AWS basati su CRT come HTTP predefinito per l'applicazione, è possibile impostare la proprietà del sistema Java su un valore `software.amazon.awssdk.http.async.service.impl` di. `software.amazon.awssdk.http.crt.AwsCrtSdkHttpService` Per impostarlo durante l'avvio dell'applicazione, eseguite un comando simile al seguente. ``` java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\ software.amazon.awssdk.http.crt.AwsCrtSdkHttpService ``` Utilizzate il seguente frammento di codice per impostare la proprietà di sistema nel codice dell'applicazione. ``` System.setProperty("software.amazon.awssdk.http.async.service.impl", "software.amazon.awssdk.http.crt.AwsCrtSdkHttpService"); ``` **Nota** È necessario aggiungere una dipendenza dall'elemento nel `poml.xml` file quando si utilizza una proprietà di sistema per configurare l'uso dei client HTTP basati su `aws-crt-client` CRT. AWS ## Configurazione avanzata dei client HTTP basati su CRT AWS È possibile utilizzare varie impostazioni di configurazione dei client HTTP AWS basati su CRT, tra cui la configurazione dello stato della connessione e il tempo massimo di inattività. È possibile esaminare le [opzioni di configurazione disponibili per.](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html) `AwsCrtAsyncHttpClient` È possibile configurare le stesse opzioni per`AwsCrtHttpClient`. ### Configurazione dello stato della connessione È possibile configurare la configurazione dello stato della connessione per i client HTTP AWS basati su CRT utilizzando il `connectionHealthConfiguration` metodo del generatore di client HTTP. L'esempio seguente crea un client di servizio S3 che utilizza un'istanza del client HTTP AWS basata su CRT configurata con la configurazione dello stato della connessione e un tempo di inattività massimo per le connessioni. ------ #### [ Synchronous client ] **Importazioni** ``` import software.amazon.awssdk.http.crt.AwsCrtHttpClient; import software.amazon.awssdk.services.s3.S3Client; import java.time.Duration; ``` **Codice** ``` // Singleton: Use the s3Client for all requests. S3Client s3Client = S3Client.builder() .httpClientBuilder(AwsCrtHttpClient .builder() .connectionHealthConfiguration(builder -> builder .minimumThroughputInBps(32000L) .minimumThroughputTimeout(Duration.ofSeconds(3))) .connectionMaxIdleTime(Duration.ofSeconds(5))) .build(); // Perform work with s3Client. // Requests complete: Close the service client. s3Client.close(); ``` ------ #### [ Asynchronous client ] **Importazioni** ``` import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient; import software.amazon.awssdk.services.s3.S3AsyncClient; import java.time.Duration; ``` **Codice** ``` // Singleton: Use the s3AsyncClient for all requests. S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .httpClientBuilder(AwsCrtAsyncHttpClient .builder() .connectionHealthConfiguration(builder -> builder .minimumThroughputInBps(32000L) .minimumThroughputTimeout(Duration.ofSeconds(3))) .connectionMaxIdleTime(Duration.ofSeconds(5))) .build(); // Perform work with s3AsyncClient. // Requests complete: Close the service client. s3AsyncClient.close(); ``` ------ ## Supporto HTTP/2 Il protocollo HTTP/2 non è ancora supportato nei client HTTP AWS basati su CRT, ma è previsto per una versione futura. Nel frattempo, se utilizzi client di servizio che richiedono il supporto HTTP/2 come the o the, considera di utilizzare invece il [KinesisAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html). [TranscribeStreamingAsyncClient[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/transcribestreaming/TranscribeStreamingAsyncClient.html) ## Esempio di configurazione del proxy Il seguente frammento di codice mostra l'uso di [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html)ciò che si utilizza per configurare l'impostazione del proxy nel codice. ------ #### [ Synchronous client ] **Importazioni** ``` import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.crt.AwsCrtHttpClient; import software.amazon.awssdk.http.crt.ProxyConfiguration; ``` **Codice** ``` SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .scheme("https") .host("myproxy") .port(1234) .username("username") .password("password") .nonProxyHosts(Set.of("localhost", "host.example.com")) .build()) .build(); ``` ------ #### [ Asynchronous client ] **Importazioni** ``` import software.amazon.awssdk.http.async.SdkAsyncHttpClient; import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient; import software.amazon.awssdk.http.crt.ProxyConfiguration; ``` **Codice** ``` SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .scheme("https") .host("myproxy") .port(1234) .username("username") .password("password") .nonProxyHosts(Set.of("localhost", "host.example.com")) .build()) .build(); ``` ------ Le proprietà di sistema Java equivalenti per la configurazione del proxy sono mostrate nel seguente frammento di riga di comando. ``` $ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \ -Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App ``` **Importante** Per utilizzare una qualsiasi delle proprietà del sistema proxy HTTPS, la `scheme` proprietà deve essere impostata nel codice su. `https` Se la proprietà scheme non è impostata nel codice, per impostazione predefinita lo schema è HTTP e l'SDK cerca `http.*` solo le proprietà di sistema. La configurazione equivalente che utilizza le variabili di ambiente è: ``` // Set the following environment variables. // $ export HTTPS_PROXY="https://username:password@myproxy:1234" // $ export NO_PROXY="localhost|host.example.com" // Set the 'useSystemPropertyValues' to false on the proxy configuration. SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .scheme("https") .useSystemPropertyValues(Boolean.FALSE) .build()) .build(); // Run the application. // $ java -cp ... App ``` # Configurazione dei proxy HTTP È possibile configurare i proxy HTTP utilizzando il codice, impostando le proprietà del sistema Java o impostando le variabili di ambiente. ## Configura nel codice I proxy vengono configurati in codice con un `ProxyConfiguration` builder specifico per il client quando si crea il client di servizio. Il codice seguente mostra un esempio di configurazione proxy per un client HTTP basato su Apache utilizzato da un client di servizio Amazon S3. ``` SdkHttpClient httpClient1 = ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://proxy.example.com")) .username("username") .password("password") .addNonProxyHost("localhost") .build()) .build(); S3Client s3Client = S3Client.builder() .httpClient(httpClient) .build(); ``` La sezione relativa a ciascun client HTTP di questo argomento mostra un esempio di configurazione proxy. + [Client Apache HTTP](http-configuration-apache.md#http-configuration-apache-proxy-conf-ex) + [URLConnectionclient HTTP basato su](http-configuration-url.md#http-configuration-url-proxy-conf-ex) + [client HTTP basato su Netty](http-configuration-netty.md#http-config-netty-proxy-ex) + [AWS Client HTTP basato su CRT](http-configuration-crt.md#http-config-crt-proxy-ex) ## Configura i proxy HTTP con impostazioni esterne Anche se non utilizzi esplicitamente un `ProxyConfiguration` builder nel codice, l'SDK cerca le impostazioni esterne per configurare una configurazione proxy predefinita. Per impostazione predefinita, l'SDK cerca innanzitutto le proprietà del sistema JVM. Se viene trovata anche una sola proprietà, l'SDK utilizza il valore e qualsiasi altro valore di proprietà di sistema. Se non sono disponibili proprietà di sistema, l'SDK cerca le variabili di ambiente proxy. L'SDK può utilizzare le seguenti proprietà di sistema e variabili di ambiente Java. **Proprietà del sistema Java** | Proprietà del sistema | Description | Supporto client HTTP | | --- | --- | --- | | http.ProxyHost | Nome host del server proxy HTTP | Tutti | | HTTP.ProxyPort | Numero di porta del server proxy HTTP | Tutti | | http.proxyUser | Nome utente per l'autenticazione del proxy HTTP | Tutti | | Http.ProxyPassword | Password per l'autenticazione del proxy HTTP | Tutti | | http. nonProxyHosts | Elenco di host che devono essere raggiunti direttamente, ignorando il proxy. [Questo elenco è valido anche quando si utilizza HTTPS](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html). | Tutti | | https://proxyHost | Nome host del server proxy HTTPS | Netty, CRT | | Porta https://proxy | Numero di porta del server proxy HTTPS | Netty, CRT | | Utente https://proxy | Nome utente per l'autenticazione proxy HTTPS | Netty, CRT | | Password https://proxy | Password per l'autenticazione del proxy HTTPS | Netty, CRT | **Variabili di ambiente** | Variabile di ambiente | Description | Supporto client HTTP | | --- | --- | --- | | HTTP\$1PROXY 1 | Un URL valido con uno schema HTTP | Tutti | | HTTPS\$1PROXY 1 | Un URL valido con uno schema HTTPS | Netty, CRT | | NO\$1PROXY 2 | Elenco di host che devono essere raggiunti direttamente, ignorando il proxy. L'elenco è valido sia per HTTP che per HTTPS. | Tutti | ### Visualizza la chiave e le note a piè di pagina **Tutti**: tutti i client HTTP offerti dall'SDK—`UrlConnectionHttpClient`,,`ApacheHttpClient`,`NettyNioAsyncHttpClient`. `AwsCrtAsyncHttpClient` **Netty**: il client HTTP basato su Netty (). `NettyNioAsyncHttpClient` **CRT** - I client HTTP AWS basati su CRT, (e). `AwsCrtHttpClient` `AwsCrtAsyncHttpClient` 1 La variabile di ambiente richiesta, indipendentemente dal fatto che sia `HTTP_PROXY` o meno`HTTPS_PROXY`, dipende dall'impostazione dello schema nel client. `ProxyConfiguration` Lo schema predefinito è HTTP. Il seguente frammento mostra come modificare lo schema in HTTPS utilizzato per la risoluzione delle variabili di ambiente. ``` SdkHttpClient httpClient = ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .scheme("https") .build()) .build(); ``` 2 La variabile di `NO_PROXY` ambiente supporta una combinazione di separatori «\$1» e «,» tra i nomi host. I nomi host possono includere il carattere jolly «\$1». ## Usa una combinazione di impostazioni È possibile utilizzare una combinazione di impostazioni del proxy HTTP nel codice, nelle proprietà di sistema e nelle variabili di ambiente. **Example — configurazione fornita da una proprietà di sistema e dal codice** ``` // Command line with the proxy password set as a system property. $ java -Dhttp.proxyPassword=SYS_PROP_password -cp ... App // Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will supplement // the proxy configuration in code with the 'http.proxyPassword' value from the system property. SdkHttpClient apacheHttpClient = ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://localhost:1234")) .username("username") .build()) .build(); // Use the apache HTTP client with proxy configuration. DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(apacheHttpClient) .build(); ``` L'SDK risolve le seguenti impostazioni proxy. ``` Host = localhost Port = 1234 Password = SYS_PROP_password UserName = username Non ProxyHost = null ``` **Example — sono disponibili sia le proprietà di sistema che le variabili di ambiente** Il `ProxyConfiguration` builder di ogni client HTTP offre impostazioni denominate `useSystemPropertyValues` e`useEnvironmentVariablesValues`. Per impostazione predefinita, entrambe le impostazioni sono`true`. Quando`true`, l'SDK utilizza automaticamente i valori delle proprietà di sistema o delle variabili di ambiente per opzioni non fornite dal `ProxyConfiguration` builder. Le proprietà di sistema hanno la precedenza sulle variabili di ambiente. Se viene trovata una proprietà del sistema proxy HTTP, l'SDK recupera ***tutti i*** valori dalle proprietà di sistema e nessuno dalle variabili di ambiente. Se desideri dare priorità alle variabili di ambiente rispetto alle proprietà di sistema, imposta su. `useSystemPropertyValues` `false` Per questo esempio, le seguenti impostazioni sono disponibili in fase di esecuzione: ``` // System properties http.proxyHost=SYS_PROP_HOST.com http.proxyPort=2222 http.password=SYS_PROP_PASSWORD http.user=SYS_PROP_USER // Environment variables HTTP_PROXY="http://EnvironmentUser:EnvironmentPassword@ENV_VAR_HOST:3333" NO_PROXY="environmentnonproxy.host,environmentnonproxy2.host:1234" ``` Il client di servizio viene creato con una delle seguenti istruzioni. Nessuna delle istruzioni imposta esplicitamente un'impostazione proxy. ``` DynamoDbClient client = DynamoDbClient.create(); DynamoDbClient client = DynamoDbClient.builder().build(); DynamoDbClient client = DynamoDbClient.builder() .httpClient(ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .build()) .build()) .build(); ``` Le seguenti impostazioni proxy vengono risolte dall'SDK: ``` Host = SYS_PROP_HOST.com Port = 2222 Password = SYS_PROP_PASSWORD UserName = SYS_PROP_USER Non ProxyHost = null ``` Poiché il client del servizio dispone di impostazioni proxy predefinite, l'SDK cerca le proprietà del sistema e quindi le variabili di ambiente. Poiché le impostazioni delle proprietà di sistema hanno la precedenza sulle variabili di ambiente, l'SDK utilizza solo le proprietà di sistema. Se l'uso delle proprietà di sistema viene modificato `false` come mostrato nel codice seguente, l'SDK risolve solo le variabili di ambiente. ``` DynamoDbClient client = DynamoDbClient.builder() .httpClient(ApacheHttpClient.builder() .proxyConfiguration(ProxyConfiguration.builder() .useSystemPropertyValues(Boolean.FALSE) .build()) .build()) .build(); ``` Le impostazioni proxy risolte tramite HTTP sono: ``` Host = ENV_VAR_HOST Port = 3333 Password = EnvironmentPassword UserName = EnvironmentUser Non ProxyHost = environmentnonproxy.host, environmentnonproxy2.host:1234 ``` # Configurazione del client HTTP basato su Apache 5.x ## Accedi ad Apache 5 HttpClient Per utilizzare il, `Apache5HttpClient` è necessario aggiungere una dipendenza **apache5-client** e configurare `Apache5HttpClient` in modo esplicito i client di servizio. ``` software.amazon.awssdk bom 2.41.0* pom import software.amazon.awssdk s3 software.amazon.awssdk apache5-client ``` \$1Sostituisci la versione mostrata in rosso con la versione di Java SDK che desideri utilizzare. Trova le ultime novità su [Maven](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) Central. ### Usa e configura il `Apache5HttpClient` È possibile configurare un'istanza `Apache5HttpClient` insieme alla creazione di un client di servizio oppure configurare una singola istanza da condividere tra più client di servizio. Con entrambi gli approcci, si utilizza [Apache5 HttpClient .Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.Builder.html) per configurare le proprietà del client HTTP basato su Apache 5. #### Procedura consigliata: dedicare un'istanza Apache5 a un client di servizio HttpClient Se devi configurare un'istanza di`Apache5HttpClient`, ti consigliamo di creare l'istanza dedicata. `Apache5HttpClient` Puoi farlo utilizzando il httpClientBuilder metodo del builder del client del servizio. In questo modo, il ciclo di vita del client HTTP viene gestito dall'SDK, che aiuta a evitare potenziali perdite di memoria se l'`Apache5HttpClient`istanza non viene chiusa quando non è più necessaria. L'esempio seguente crea un S3Client e configura l'istanza incorporata di con i valori MaxConnections e ConnectionTimeout. `Apache5HttpClient` L'istanza HTTP viene creata utilizzando il metodo di. `httpClientBuilder` `S3Client.Builder` **Importazioni** ``` import software.amazon.awssdk.http.apache5.Apache5HttpClient; import software.amazon.awssdk.services.s3.S3Client; import java.time.Duration; ``` **Codice** ``` S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests. .builder() .httpClientBuilder(Apache5HttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) ) .build(); // Perform work with the s3Client. s3Client.close(); // Requests completed: Close all service clients. ``` #### Approccio alternativo: condividere un'`Apache5HttpClient`istanza Per ridurre l'utilizzo di risorse e memoria per l'applicazione, è possibile configurarne un'applicazione `Apache5HttpClient` e condividerla tra più client di servizio. Il pool di connessioni HTTP verrà condiviso, il che riduce l'utilizzo delle risorse. **Nota** Quando un'`Apache5HttpClient`istanza è condivisa, è necessario chiuderla quando è pronta per essere eliminata. L'SDK non chiuderà l'istanza quando il client del servizio viene chiuso. L'esempio seguente configura un client HTTP basato su Apache utilizzato da due client di servizio. L'`ApacheHttpClient`istanza configurata viene passata al metodo HttpClient di ogni builder. Quando i client di servizio e il client HTTP non sono più necessari, il codice li chiude esplicitamente. Il codice chiude per ultimo il client HTTP. **Importazioni** ``` import software.amazon.awssdk.http.SdkHttpClient; import software.amazon.awssdk.http.apache5.Apache5HttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.s3.S3Client; ``` **Codice** ``` SdkHttpClient apache5HttpClient = Apache5HttpClient.builder() .maxConnections(100).build(); // Singletons: Use the s3Client and dynamoDbClient for all requests. S3Client s3Client = S3Client.builder() .httpClient(apache5HttpClient).build(); DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .httpClient(apache5HttpClient).build(); // Perform work with the s3Client and dynamoDbClient. // Requests completed: Close all service clients. s3Client.close(); dynamoDbClient.close(); apache5HttpClient.close(); // Explicitly close apache5HttpClient. ``` # Usa gli intercettori di esecuzione in AWS SDK for Java 2.x Intercettori di esecuzione integrati nel ciclo di AWS SDK for Java 2.x vita di richiesta e risposta per eseguire logiche personalizzate nelle varie fasi dell'esecuzione delle chiamate API. Utilizza gli intercettori per implementare problemi trasversali come la registrazione, la raccolta delle metriche, la modifica delle richieste, il debug e la gestione degli errori. Gli interceptor implementano l'interfaccia, che fornisce hook per le diverse fasi di esecuzione della richiesta [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/interceptor/ExecutionInterceptor.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/interceptor/ExecutionInterceptor.html). ## Ciclo di vita degli intercettori L'`ExecutionInterceptor`interfaccia fornisce metodi che vengono chiamati in punti specifici durante l'esecuzione della richiesta: + `beforeExecution`- Chiamato prima dell'esecuzione della richiesta + `modifyRequest`- Modifica l'oggetto della richiesta SDK + `beforeMarshalling`- Chiamato prima che la richiesta passi a HTTP + `afterMarshalling`- Chiamato dopo la richiesta marshals to HTTP + `modifyHttpRequest`- Modifica la richiesta HTTP + `beforeTransmission`- Chiamato prima dell'invio della richiesta HTTP + `afterTransmission`- Chiamato dopo la ricezione della risposta HTTP + `modifyHttpResponse`- Modifica la risposta HTTP + `beforeUnmarshalling`- Chiamato prima che la risposta HTTP unmarshals + `afterUnmarshalling`- Chiamato dopo la risposta HTTP unmarshals + `modifyResponse`- Modifica l'oggetto di risposta SDK + `afterExecution`- Chiamato dopo l'esecuzione corretta della richiesta + `onExecutionFailure`- Chiamato quando l'esecuzione della richiesta fallisce ## Registra gli intercettori Registra gli intercettori quando crei un client di servizio utilizzando il metodo. `overrideConfiguration` Puoi registrare più intercettori e questi vengono eseguiti nell'ordine in cui li registri. ``` // Register a single interceptor. SqsClient client = SqsClient.builder() .overrideConfiguration(c -> c.addExecutionInterceptor(new LoggingInterceptor())) .build(); // Register multiple interceptors. S3Client s3Client = S3Client.builder() .overrideConfiguration(config -> config .addExecutionInterceptor(new TimingInterceptor()) .addExecutionInterceptor(new LoggingInterceptor()) .addExecutionInterceptor(new RequestModificationInterceptor())) .build(); ``` ## Esempio di intercettore La seguente classe dimostra come utilizzare gli intercettori di esecuzione per aggiungere problemi trasversali come la registrazione, il monitoraggio delle prestazioni e le richieste di modifica alle operazioni S3 senza modificare la logica aziendale principale. Questo esempio mostra come registrare più intercettori su un client S3 e vederli in azione durante chiamate API reali. AWS ### Importazioni ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import software.amazon.awssdk.awscore.exception.AwsServiceException; import software.amazon.awssdk.core.ApiName; import software.amazon.awssdk.core.SdkRequest; import software.amazon.awssdk.core.interceptor.Context; import software.amazon.awssdk.core.interceptor.ExecutionAttributes; import software.amazon.awssdk.core.interceptor.ExecutionInterceptor; import software.amazon.awssdk.http.SdkHttpRequest; import software.amazon.awssdk.http.SdkHttpResponse; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.HeadBucketRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; import java.time.Duration; import java.time.Instant; ``` ``` public class S3InterceptorsDemo { private static final Logger logger = LoggerFactory.getLogger(S3InterceptorsDemo.class); public static void main(String[] args) { logger.info("=== AWS SDK for Java v2 - S3 Interceptors Demo ==="); // Create an S3 client with multiple interceptors. S3Client s3Client = S3Client.builder() .overrideConfiguration(config -> config .addExecutionInterceptor(new TimingInterceptor()) .addExecutionInterceptor(new LoggingInterceptor()) .addExecutionInterceptor(new RequestModificationInterceptor())) .build(); try { logger.info("Starting S3 operations with interceptors..."); // Operation 1: List buckets. logger.info("Operation 1: Listing S3 buckets"); logger.info("----------------------------------------"); ListBucketsResponse listBucketsResponse = s3Client.listBuckets(); logger.info("Found {} buckets", listBucketsResponse.buckets().size()); // Operation 2: Try to access a bucket that likely doesn't exist. logger.info("Operation 2: Checking non-existent bucket (demonstrating error interceptor)"); logger.info("----------------------------------------"); try { s3Client.headBucket(HeadBucketRequest.builder() .bucket("amzn-s3-demo-bucket-that-does-not-exist-1234") .build()); } catch (Exception e) { logger.info("Expected error occurred (interceptor should have logged it)"); } } catch (Exception e) { logger.error(" Error during S3 operations: {}", e.getMessage(), e); } finally { s3Client.close(); logger.info("Demo completed - S3 client closed"); } } // Logging interceptor. private static class LoggingInterceptor implements ExecutionInterceptor { private static final Logger logger = LoggerFactory.getLogger(LoggingInterceptor.class); @Override public void beforeExecution(Context.BeforeExecution context, ExecutionAttributes executionAttributes) { logger.info("[LOGGING] Starting request: {}", context.request().getClass().getSimpleName()); } @Override public void afterExecution(Context.AfterExecution context, ExecutionAttributes executionAttributes) { logger.info("[LOGGING] Completed request: {}", context.request().getClass().getSimpleName()); } @Override public void onExecutionFailure(Context.FailedExecution context, ExecutionAttributes executionAttributes) { logger.error("[LOGGING] Request failed: {}", context.request().getClass().getSimpleName()); if (context.exception() instanceof AwsServiceException) { AwsServiceException ase = (AwsServiceException) context.exception(); if (ase.awsErrorDetails().errorCode() != null) { SdkHttpResponse httpResponse = ase.awsErrorDetails().sdkHttpResponse(); logger.error(" HTTP Status: {}", httpResponse.statusCode()); logger.error(" Error Code: {}", ase.awsErrorDetails().errorCode()); logger.error(" Error Message: {}", ase.awsErrorDetails().errorMessage()); } } } } // Performance timing interceptor. private static class TimingInterceptor implements ExecutionInterceptor { private static final Logger logger = LoggerFactory.getLogger(TimingInterceptor.class); private Instant startTime; @Override public void beforeExecution(Context.BeforeExecution context, ExecutionAttributes executionAttributes) { startTime = Instant.now(); logger.info("⏱️ [TIMING] Request started at: {}", startTime); } @Override public void afterExecution(Context.AfterExecution context, ExecutionAttributes executionAttributes) { if (startTime != null) { Duration duration = Duration.between(startTime, Instant.now()); logger.info("⏱️ [TIMING] Request completed in: {}ms", duration.toMillis()); } } @Override public void onExecutionFailure(Context.FailedExecution context, ExecutionAttributes executionAttributes) { if (startTime != null) { Duration duration = Duration.between(startTime, Instant.now()); logger.warn("⏱️ [TIMING] Request failed after: {}ms", duration.toMillis()); } } } // Request modification interceptor private static class RequestModificationInterceptor implements ExecutionInterceptor { private static final Logger logger = LoggerFactory.getLogger(RequestModificationInterceptor.class); @Override public SdkRequest modifyRequest(Context.ModifyRequest context, ExecutionAttributes executionAttributes) { SdkRequest originalRequest = context.request(); logger.info("[MODIFY] Modifying request: {}", originalRequest.getClass().getSimpleName()); // For ListBucketsRequest, we can't modify much since it has no settable properties // For HeadBucketRequest, we can demonstrate modifying the request if (originalRequest instanceof HeadBucketRequest) { HeadBucketRequest headRequest = (HeadBucketRequest) originalRequest; // Create a new request with an API name added. return HeadBucketRequest.builder() .bucket(headRequest.bucket()) .overrideConfiguration(b -> b.addApiName(ApiName.builder() .name("My-API") .version("1.0") .build())) .build(); } logger.info("Not a HeadBucketRequest, returning original request"); return originalRequest; } @Override public SdkHttpRequest modifyHttpRequest(Context.ModifyHttpRequest context, ExecutionAttributes executionAttributes) { logger.info("[MODIFY] Adding custom HTTP headers"); return context.httpRequest().toBuilder() .putHeader("X-Custom-Header", "S3InterceptorDemo") .putHeader("X-Request-ID", java.util.UUID.randomUUID().toString()) .build(); } } } ``` ### File pom Maven ``` 4.0.0 org.example interceptors-examples 1.0.0 jar interceptors-examples Demonstration of execution interceptors in AWS SDK for Java v2 17 17 UTF-8 2.31.62 org.example.S3InterceptorsDemo software.amazon.awssdk bom ${aws.java.sdk.version} pom import org.apache.logging.log4j log4j-bom 2.23.1 pom import software.amazon.awssdk s3 org.apache.logging.log4j log4j-core org.slf4j slf4j-api 2.0.13 org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-1.2-api org.junit.jupiter junit-jupiter 5.10.1 test org.apache.maven.plugins maven-compiler-plugin 3.11.0 17 17 org.apache.maven.plugins maven-surefire-plugin 3.2.2 org.codehaus.mojo exec-maven-plugin 3.1.0 ${exec.mainClass} org.apache.maven.plugins maven-shade-plugin 3.4.1 package shade ${exec.mainClass} false ``` ## Best practice + **Mantieni gli intercettori leggeri**: gli intercettori vengono eseguiti per ogni richiesta, in modo da evitare calcoli pesanti o operazioni di blocco che potrebbero influire sulle prestazioni. + **Gestisci le eccezioni in modo corretto: se l'**intercettore genera un'eccezione, l'intera richiesta non va a buon fine. Usa sempre i blocchi try-catch per operazioni che potrebbero fallire. + **L'ordine è importante**: gli intercettori vengono eseguiti nell'ordine in cui li registri. Considerate le dipendenze tra i vostri intercettori quando li registrate. + **Usa ExecutionAttributes per lo stato**: se devi passare dati tra diversi metodi di intercettazione, usa variabili `ExecutionAttributes` anziché di istanza per garantire la sicurezza dei thread. + **Fai attenzione ai dati sensibili**: quando registri richieste e risposte, fai attenzione a non registrare informazioni sensibili come credenziali o dati personali. ## Oggetti contestuali Ogni metodo interceptor riceve un oggetto contestuale che fornisce l'accesso alle informazioni di richiesta e risposta nelle diverse fasi dell'esecuzione: + `Context.BeforeExecution`- Fornisce l'accesso alla richiesta SDK originale + `Context.ModifyRequest`- Modifica la richiesta SDK + `Context.ModifyHttpRequest`- Modifica la richiesta HTTP + `Context.AfterExecution`- Fornisce accesso sia alla richiesta che alla risposta + `Context.FailedExecution`- Fornisce l'accesso alla richiesta e all'eccezione che si è verificata