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à.
# Lavora con i metadati delle istanze Amazon EC2
Un client Java SDK per Amazon EC2 Instance Metadata Service (client di metadati) consente alle applicazioni di accedere ai metadati sulla loro istanza EC2 locale. Il client di metadati funziona con l'istanza locale di [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)(Instance Metadata Service v2) e utilizza richieste orientate alla sessione.
Nell'SDK sono disponibili due classi di client. Il sincrono `[Ec2MetadataClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataClient.html)` serve per bloccare le operazioni e l'altro per i casi d'uso asincroni e [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataAsyncClient.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataAsyncClient.html)non bloccanti.
## Nozioni di base
Per utilizzare il client di metadati, aggiungi l'artefatto Maven al tuo progetto`imds`. Sono inoltre necessarie classi per un `[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)` (o un `[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)` per la variante asincrona) sul classpath.
Il seguente codice XML Maven mostra i frammenti di dipendenza per l'utilizzo del sincrono insieme alla dipendenza per i client di metadati. [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)
```
software.amazon.awssdk
bom
VERSION
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
url-connection-client
```
Cerca nel repository centrale di [Maven la versione più recente](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) dell'artefatto. `bom`
Per utilizzare un client HTTP asincrono, sostituisci lo snippet di dipendenza per l'artefatto. `url-connection-client` Ad esempio, il seguente frammento introduce l'implementazione. [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)
```
software.amazon.awssdk
netty-nio-client
```
## Usa il client di metadati
### Crea un'istanza di un client di metadati
È possibile creare un'istanza di un sistema sincrono `Ec2MetadataClient` quando nel classpath è presente una sola implementazione dell'`SdkHttpClient`interfaccia. A tale scopo, chiamate il `Ec2MetadataClient#create()` metodo statico come illustrato nel frammento seguente.
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
Se l'applicazione ha più implementazioni dell'`SdkHttpAsyncClient`interfaccia `SdkHttpClient` or, è necessario specificare un'implementazione da utilizzare per il client di metadati, come illustrato nella sezione. [Client HTTP configurabile](#examples-ec2-IMDS-features-http)
**Nota**
Per la maggior parte dei client di servizi, come Amazon S3, l'SDK for Java aggiunge automaticamente implementazioni dell'interfaccia or. `SdkHttpClient` `SdkHttpAsyncClient` Se il tuo client di metadati utilizza la stessa implementazione, funzionerà. `Ec2MetadataClient#create()` Se hai bisogno di un'implementazione diversa, devi specificarla quando crei il client di metadati.
### Inviare richieste
[Per recuperare i metadati dell'istanza, create un'istanza della `EC2MetadataClient` classe e chiamate il `get` metodo con un parametro path che specifica la categoria di metadati dell'istanza.](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html)
L'esempio seguente stampa il valore associato alla chiave sulla console. `ami-id`
```
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/ami-id");
System.out.println(response.asString());
client.close(); // Closes the internal resources used by the Ec2MetadataClient class.
```
Se il percorso non è valido, il `get` metodo genera un'eccezione.
Riutilizzate la stessa istanza del client per più richieste, ma chiamate `close` il client quando non è più necessario per rilasciare risorse. Dopo la chiamata del metodo close, l'istanza del client non può più essere utilizzata.
### Analizza le risposte
I metadati delle istanze EC2 possono essere emessi in diversi formati. Il testo normale e il JSON sono i formati più utilizzati. I client di metadati offrono modi per lavorare con questi formati.
Come illustrato nell'esempio seguente, utilizzate il `asString` metodo per ottenere i dati come stringa Java. È inoltre possibile utilizzare il `asList` metodo per separare una risposta in testo semplice che restituisce più righe.
```
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List splits = response.asList();
```
Se la risposta è in JSON, utilizzate il `Ec2MetadataResponse#asDocument` metodo per analizzare la risposta JSON in un'istanza [Document](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/Document.html), come mostrato nel seguente frammento di codice.
```
Document fullResponse = response.asDocument();
```
Verrà generata un'eccezione se il formato dei metadati non è in JSON. Se la risposta viene analizzata correttamente, puoi utilizzare l'[API del documento](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) per esaminare la risposta in modo più dettagliato. Consulta la [tabella delle categorie di metadati](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) delle istanze per scoprire quali categorie di metadati forniscono risposte in formato JSON.
## Configura un client di metadati
### Tentativi
È possibile configurare un client di metadati con un meccanismo di ripetizione dei tentativi. In tal caso, il client può riprovare automaticamente le richieste che non vanno a buon fine per motivi imprevisti. Per impostazione predefinita, il client riprova tre volte in caso di richiesta non riuscita, con un tempo di backoff esponenziale tra un tentativo e l'altro.
Se il tuo caso d'uso richiede un meccanismo di ripetizione dei tentativi diverso, puoi personalizzare il client utilizzando il metodo del relativo generatore. `retryPolicy` Ad esempio, l'esempio seguente mostra un client sincrono configurato con un ritardo fisso di due secondi tra i tentativi e cinque tentativi.
```
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
.backoffStrategy(fixedBackoffStrategy))
.build();
```
Ce ne sono diversi [BackoffStrategies](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/backoff/package-summary.html)che è possibile utilizzare con un client di metadati.
Puoi anche disabilitare completamente il meccanismo di riprova, come mostra il seguente frammento.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(Ec2MetadataRetryPolicy.none())
.build();
```
L'utilizzo `Ec2MetadataRetryPolicy#none()` disattiva la politica di riprova predefinita in modo che il client di metadati non tenti di ripetere i tentativi.
### Versione IP
Per impostazione predefinita, un client di metadati utilizza l'endpoint in. IPV4 `http://169.254.169.254` Per modificare il client in modo che utilizzi la IPV6 versione, usa il metodo `endpointMode` o il `endpoint` metodo del generatore. Si verifica un'eccezione se entrambi i metodi vengono chiamati sul builder.
Gli esempi seguenti mostrano entrambe le IPV6 opzioni.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
```
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpoint(URI.create("http://[fd00:ec2::254]"))
.build();
```
## Funzionalità principali
### Client asincrono
Per utilizzare la versione non bloccante del client, crea un'istanza della classe. `Ec2MetadataAsyncClient` Il codice nell'esempio seguente crea un client asincrono con impostazioni predefinite e utilizza il `get` metodo per recuperare il valore della chiave. `ami-id`
```
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture response = asyncClient.get("/latest/meta-data/ami-id");
```
Il valore `java.util.concurrent.CompletableFuture` restituito dal `get` metodo viene completato quando viene restituita la risposta. L'esempio seguente stampa i `ami-id` metadati sulla console.
```
response.thenAccept(metadata -> System.out.println(metadata.asString()));
```
### Client HTTP configurabile
Il generatore di ogni client di metadati dispone di un `httpClient` metodo che puoi utilizzare per fornire un client HTTP personalizzato.
L'esempio seguente mostra il codice per un'istanza personalizzata`UrlConnectionHttpClient`.
```
SdkHttpClient httpClient =
UrlConnectionHttpClient.builder()
.socketTimeout(Duration.ofMinutes(5))
.proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.example.net:8888"))))
.build();
Ec2MetadataClient metaDataClient =
Ec2MetadataClient.builder()
.httpClient(httpClient)
.build();
// Use the metaDataClient instance.
metaDataClient.close(); // Close the instance when no longer needed.
```
L'esempio seguente mostra il codice per un'`NettyNioAsyncHttpClient`istanza personalizzata con un client di metadati asincrono.
```
SdkAsyncHttpClient httpAsyncClient =
NettyNioAsyncHttpClient.builder()
.connectionTimeout(Duration.ofMinutes(5))
.maxConcurrency(100)
.build();
Ec2MetadataAsyncClient asyncMetaDataClient =
Ec2MetadataAsyncClient.builder()
.httpClient(httpAsyncClient)
.build();
// Use the asyncMetaDataClient instance.
asyncMetaDataClient.close(); // Close the instance when no longer needed.
```
L'[Configurare i client HTTP in AWS SDK for Java 2.x](http-configuration.md)argomento di questa guida fornisce dettagli su come configurare i client HTTP disponibili nell'SDK for Java.
### Memorizzazione nella cache dei token
Poiché i client utilizzano i metadati IMDSv2, tutte le richieste sono associate a una sessione. Una sessione è definita da un token con scadenza, che il client di metadati gestisce per voi. Ogni richiesta di metadati riutilizza automaticamente il token fino alla scadenza.
Per impostazione predefinita, un token dura sei ore (21.600 secondi). Ti consigliamo di mantenere il time-to-live valore predefinito, a meno che il tuo caso d'uso specifico non richieda una configurazione avanzata.
Se necessario, configura la durata utilizzando il metodo `tokenTtl` builder. Ad esempio, il codice nel frammento seguente crea un client con una durata della sessione di cinque minuti.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.tokenTtl(Duration.ofMinutes(5))
.build();
```
Se omettete di chiamare il `tokenTtl` metodo sul builder, viene invece utilizzata la durata predefinita di 21.600.