Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
Mit Amazon EC2 EC2-EC2-Instance-Metadaten arbeiten
Ein Java SDK-Client für den Amazon EC2 Instance Metadata Service (Metadaten-Client) ermöglicht Ihren Anwendungen den Zugriff auf Metadaten auf ihrer lokalen EC2-Instance. Der Metadaten-Client arbeitet mit der lokalen Instanz von IMDSv2 (Instance Metadata Service v2) und verwendet sitzungsorientierte Anfragen.
Zwei Client-Klassen sind im SDK verfügbar. Die synchroneEc2MetadataClient ist für blockierende Operationen und die Ec2MetadataAsyncClient
Erste Schritte
Um den Metadaten-Client zu verwenden, fügen Sie dasimds Maven-Artefakt zu Ihrem Projekt hinzu. Sie benötigen auch Klassen für eineSdkHttpClient (oder eineSdkAsyncHttpClient für die asynchrone Variante) im Klassenpfad.
Das folgende Maven-XML zeigt Abhängigkeitsschnipsel für die Verwendung von Synchron 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>
Suchen Sie im zentralen Maven-Repositorybom Artefakts.
Um einen asynchronen HTTP-Client zu verwenden, ersetzen Sie das Abhängigkeits-Snippet für dasurl-connection-client Artefakt. Das folgende Snippet enthält beispielsweise die NettyNioAsyncHttpClient
<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>netty-nio-client</artifactId> </dependency>
Verwenden Sie den Metadaten-Client
Instanziieren Sie einen Metadaten-Client
Sie können eine Instanz eines Synchronous instanziieren,Ec2MetadataClient wenn nur eine Implementierung derSdkHttpClient Schnittstelle im Klassenpfad vorhanden ist. Rufen Sie dafür die statischeEc2MetadataClient#create() Methode auf, wie im folgenden Snippet gezeigt.
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
Wenn Ihre Anwendung mehrere Implementierungen derSdkHttpClientSdkHttpAsyncClient OR-Schnittstelle hat, müssen Sie eine Implementierung angeben, die der Metadaten-Client verwenden soll, wie imKonfigurierbarer HTTP-Client Abschnitt gezeigt.
Anmerkung
Für die meisten Service-Clients, wie Amazon S3, fügt das SDK for Java automatisch Implementierungen derSdkHttpClientSdkHttpAsyncClient OR-Schnittstelle hinzu. Wenn Ihr Metadaten-Client dieselbe Implementierung verwendet,Ec2MetadataClient#create() funktioniert das. Wenn Sie eine andere Implementierung benötigen, müssen Sie diese angeben, wenn Sie den Metadaten-Client erstellen.
Anfragen senden
Um Instanzmetadaten abzurufen, instanziieren Sie dieEC2MetadataClient Klasse und rufen Sie dieget Methode mit einem Pfadparameter auf, der die Metadatenkategorie der Instanz angibt.
Das folgende Beispiel druckt den Wert, der demami-id Schlüssel zugeordnet ist, an die Konsole.
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.
Wenn der Pfad nicht gültig ist, löst dieget Methode eine Ausnahme aus.
Verwenden Sie dieselbe Client-Instanz für mehrere Anfragen wieder, rufen Sie den Client jedochclose an, wenn er nicht mehr benötigt wird, um Ressourcen freizugeben. Nach dem Aufruf der Close-Methode kann die Client-Instanz nicht mehr verwendet werden.
Antworten analysieren
EC2-Instanzmetadaten können in verschiedenen Formaten ausgegeben werden. Klartext und JSON sind die am häufigsten verwendeten Formate. Die Metadaten-Clients bieten Möglichkeiten, mit diesen Formaten zu arbeiten.
Wie das folgende Beispiel zeigt, verwenden Sie dieasString Methode, um die Daten als Java-Zeichenfolge abzurufen. Sie können dieasList Methode auch verwenden, um eine Klartextantwort zu trennen, die mehrere Zeilen zurückgibt.
Ec2MetadataClient client = Ec2MetadataClient.create(); Ec2MetadataResponse response = client.get("/latest/meta-data/"); String fullResponse = response.asString(); List<String> splits = response.asList();
Wenn die Antwort in JSON ist, verwenden Sie dieEc2MetadataResponse#asDocument Methode, um die JSON-Antwort in eine Dokumentinstanz
Document fullResponse = response.asDocument();
Eine Ausnahme wird ausgelöst, wenn das Format der Metadaten nicht in JSON ist. Wenn die Antwort erfolgreich analysiert wurde, können Sie die Dokument-API
Einen Metadaten-Client konfigurieren
Wiederholversuche
Sie können einen Metadaten-Client mit einem Wiederholungsmechanismus konfigurieren. Wenn Sie dies tun, kann der Client Anfragen, die aus unerwarteten Gründen fehlschlagen, automatisch wiederholen. Standardmäßig versucht es der Client bei einer fehlgeschlagenen Anfrage dreimal mit einer exponentiellen Backoff-Zeit zwischen den Versuchen.
Wenn Ihr Anwendungsfall einen anderen Wiederholungsmechanismus erfordert, können Sie den Client mithilfe derretryPolicy Methode in seinem Builder anpassen. Das folgende Beispiel zeigt beispielsweise einen synchronen Client, der mit einer festen Verzögerung von zwei Sekunden zwischen Versuchen und fünf Wiederholungsversuchen konfiguriert ist.
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2)); Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5) .backoffStrategy(fixedBackoffStrategy)) .build();
Es gibt mehrere BackoffStrategies
Sie können den Wiederholungsmechanismus auch vollständig deaktivieren, wie das folgende Snippet zeigt.
Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(Ec2MetadataRetryPolicy.none()) .build();
Bei VerwendungEc2MetadataRetryPolicy#none() wird die standardmäßige Wiederholungsrichtlinie deaktiviert, sodass der Metadaten-Client keine Wiederholungsversuche unternimmt.
IP-Version
Standardmäßig verwendet ein Metadaten-Client den IPV4-Endpunkt unterhttp://169.254.169.254. Um den Client so zu ändern, dass er die IPV6-Version verwendet, verwenden Sie entweder dieendpointMode oder dieendpoint Methode des Builders. Eine Ausnahme entsteht, wenn beide Methoden im Builder aufgerufen werden.
Die folgenden Beispiele zeigen beide IPv6-Optionen.
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpointMode(EndpointMode.IPV6) .build();
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpoint(URI.create("http://[fd00:ec2::254]")) .build();
Schlüsselfunktionen
Asynchroner Client
Um die nicht blockierende Version des Clients zu verwenden, instanziieren Sie eine Instanz derEc2MetadataAsyncClient Klasse. Der Code im folgenden Beispiel erstellt einen asynchronen Client mit Standardeinstellungen und verwendet dieget Methode, um den Wert für denami-id Schlüssel abzurufen.
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create(); CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");
Das von derget Methodejava.util.concurrent.CompletableFuture zurückgegebene Ergebnis ist abgeschlossen, wenn die Antwort zurückgegeben wird. Im folgenden Beispiel werden dieami-id Metadaten auf die Konsole gedruckt.
response.thenAccept(metadata -> System.out.println(metadata.asString()));
Konfigurierbarer HTTP-Client
Der Builder für jeden Metadaten-Client verfügt über einehttpClient Methode, mit der Sie einen benutzerdefinierten HTTP-Client bereitstellen können.
Das folgende Beispiel zeigt den Code für eine benutzerdefinierteUrlConnectionHttpClient Instanz.
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.
Das folgende Beispiel zeigt Code für eine benutzerdefinierteNettyNioAsyncHttpClient Instanz mit einem asynchronen Metadatenclient.
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.
DasHTTP-Clients Thema in diesem Handbuch enthält Einzelheiten zur Konfiguration der HTTP-Clients, die im SDK for Java verfügbar sind.
Zwischenspeichern von Token
Da die Metadaten-Clients IMDSv2 verwenden, sind alle Anfragen einer Sitzung zugeordnet. Eine Sitzung wird durch ein Token mit einem Ablaufdatum definiert, das der Metadaten-Client für Sie verwaltet. Jede Metadatenanfrage verwendet das Token automatisch wieder, bis es abläuft.
Standardmäßig dauert ein Token sechs Stunden (21 600 Sekunden). Wir empfehlen, den time-to-live Standardwert, es sei denn, Ihr spezieller Anwendungsfall erfordert, eine erweiterte Konfiguration.
Konfigurieren Sie die Dauer bei Bedarf mithilfe dertokenTtl Builder-Methode. Der Code im folgenden Codeausschnitt erstellt beispielsweise einen Client mit einer Sitzungsdauer von fünf Minuten.
Ec2MetadataClient client = Ec2MetadataClient.builder() .tokenTtl(Duration.ofMinutes(5)) .build();
Wenn Sie den Aufruf dertokenTtl Methode im Builder auslassen, wird stattdessen die Standarddauer von 21.600 verwendet.
