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à.
Utilizzare 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 (Instance Metadata Service v2) e utilizza richieste orientate alla sessione.
Nell'SDK sono disponibili due classi client. La modalità sincronaEc2MetadataClient serve per bloccare le operazioni e Ec2MetadataAsyncClient
Nozioni di base
Per utilizzare il client di metadati, aggiungi l'artefattoimds Maven al tuo progetto. Sono necessarie anche le classi per unSdkHttpClient (o unSdkAsyncHttpClient per la variante asincrona) sul classpath.
Il seguente Maven XML mostra i frammenti di dipendenza per l'utilizzo del client sincrono UrlConnectionHttpClient
<dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>VERSION</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>imds</artifactId> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>url-connection-client</artifactId> </dependency> <!-- other dependencies --> </dependencies>
Cerca nel repository centrale di Mavenbomartefatto.
Per utilizzare un client HTTP asincrono, sostituisci il frammento di dipendenza per l'url-connection-clientartefatto. Ad esempio, il seguente frammento di codice introduce l'NettyNioAsyncHttpClient
<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>netty-nio-client</artifactId> </dependency>
Usa il client di metadati
Crea un'istanza di un client di metadati
È possibile creare un'istanza di un sistema sincronoEc2MetadataClient quando nel classpath è presente una sola implementazione dell'SdkHttpClientinterfaccia. Per fare ciò, chiama ilEc2MetadataClient#create() metodo statico come visualizzato nel frammento seguente.
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
Se l'applicazione ha più implementazioni dell'SdkHttpAsyncClientinterfacciaSdkHttpClient or, è necessario specificare un'implementazione da utilizzare per il client di metadati, come mostrato nellaClient HTTP configurabile sezione.
Nota
Per la maggior parte dei client di servizi, come Amazon S3, l'SDK for Java aggiunge automaticamente le implementazioni dell'SdkHttpAsyncClientinterfacciaSdkHttpClient or. Se il tuo client di metadati utilizza la stessa implementazione,Ec2MetadataClient#create() funzionerà. Se è necessaria un'implementazione diversa, è necessario specificarla quando si crea il client di metadati.
Invia richieste
Per recuperare i metadati dell'istanza, create un'istanza dellaEC2MetadataClient classe e chiamate ilget metodo con un parametro path che specifica la categoria dei metadati dell'istanza.
L'esempio seguente stampa il valore associato allaami-id chiave sulla console.
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, ilget metodo genera un'eccezione.
Riutilizza la stessa istanza client per più richieste, ma richiamaclose il client quando non è più necessario rilasciare risorse. Dopo aver chiamato il metodo close, l'istanza client non può più essere utilizzata.
Analizza le risposte
I metadati delle istanze EC2 possono essere emessi in diversi formati. Testo normale e JSON sono i formati più comunemente usati. I client di metadati offrono modi per lavorare con questi formati.
Come mostra l'esempio seguente, usa ilasString metodo per ottenere i dati come stringa Java. È inoltre possibile utilizzare ilasList metodo per separare una risposta in testo normale che restituisce più righe.
Ec2MetadataClient client = Ec2MetadataClient.create(); Ec2MetadataResponse response = client.get("/latest/meta-data/"); String fullResponse = response.asString(); List<String> splits = response.asList();
Se la risposta è in JSON, utilizza ilEc2MetadataResponse#asDocument metodo per analizzare la risposta JSON in un'istanza Document
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
Configurazione di un client di metadati
Tentativi
È possibile configurare un client di metadati con un meccanismo di riprova. In tal caso, il client può riprovare automaticamente le richieste che falliscono per motivi imprevisti. Per impostazione predefinita, il client riprova tre volte su una richiesta non riuscita con un tempo di backoff esponenziale tra i tentativi.
Se il tuo caso d'uso richiede un meccanismo di ripetizione diverso, puoi personalizzare il client utilizzando ilretryPolicy metodo del relativo generatore. Ad esempio, l'esempio seguente mostra un client sincrono configurato con un ritardo fisso di due secondi tra i tentativi e cinque tentativi di ripetizione.
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2)); Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5) .backoffStrategy(fixedBackoffStrategy)) .build();
Ce ne sono diversi BackoffStrategies
Puoi anche disabilitare completamente il meccanismo di ripetizione, come mostra il frammento seguente.
Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(Ec2MetadataRetryPolicy.none()) .build();
L'utilizzoEc2MetadataRetryPolicy#none() disabilita la politica di ripetizione predefinita in modo che il client di metadati non tenti nuovi tentativi.
Versione IP
Per impostazione predefinita, un client di metadati utilizza l'endpoint IPV4 all'indirizzohttp://169.254.169.254. Per modificare il client in modo che utilizzi la versione IPV6, utilizza il metodoendpointMode o ilendpoint metodo del generatore. Si verifica un'eccezione se entrambi i metodi vengono chiamati sul builder.
Negli esempi seguenti vengono mostrate entrambe le opzioni IPV6.
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpointMode(EndpointMode.IPV6) .build();
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpoint(URI.create("http://[fd00:ec2::254]")) .build();
Caratteristiche principali
Client asincrona
Per utilizzare la versione non bloccante del client, create un'istanza dellaEc2MetadataAsyncClient classe. Il codice nell'esempio seguente crea un client asincrono con impostazioni predefinite e utilizza ilget metodo per recuperare il valore dellaami-id chiave.
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create(); CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");
Il valorejava.util.concurrent.CompletableFuture restituito dalget metodo viene completato quando viene restituita la risposta. L'esempio seguente stampa iami-id metadati sulla console.
response.thenAccept(metadata -> System.out.println(metadata.asString()));
Client HTTP configurabile
Il generatore di ogni client di metadati dispone di unhttpClient metodo che è possibile utilizzare per fornire un client HTTP personalizzato.
L'esempio seguente mostra il codice per un'UrlConnectionHttpClientistanza personalizzata.
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'NettyNioAsyncHttpClientistanza 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'HTTPclientiargomento di questa guida fornisce dettagli su come configurare i client HTTP disponibili nell'SDK for Java.
Memorizzazione nella cache dei token
Poiché i client di metadati utilizzano IMDSv2, tutte le richieste sono associate a una sessione. Una sessione è definita da un token con una scadenza, che il client di metadati gestisce per te. Ogni richiesta di metadati riutilizza automaticamente il token fino alla sua scadenza.
Per impostazione di default, un token dura sei ore (21.600 secondi). Ti consigliamo di mantenere il time-to-live valore predefinito, a meno che il caso d'uso specifico non richieda una configurazione avanzata.
Se necessario, configura la durata utilizzando il metodotokenTtl builder. Ad esempio, il codice nel seguente frammento di codice crea un client con una durata della sessione di cinque minuti.
Ec2MetadataClient client = Ec2MetadataClient.builder() .tokenTtl(Duration.ofMinutes(5)) .build();
Se si omette di chiamare iltokenTtl metodo sul builder, viene invece utilizzata la durata predefinita di 21.600.
