Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Trabajar con metadatos de la instancia de Amazon EC2
Un cliente Java SDK para el servicio de metadatos de la instancia de Amazon EC2 (cliente de metadatos) permite a sus aplicaciones acceder a los metadatos de su instancia EC2 local. El cliente de metadatos funciona con la instancia local de [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)(Instance Metadata Service v2) y utiliza solicitudes orientadas a la sesión.
Hay dos clases de clientes disponibles en el SDK. El síncrono `[Ec2MetadataClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataClient.html)` es para operaciones de bloqueo, y el [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) es para casos prácticos asíncronos, no de bloqueo.
## Introducción
Para usar el cliente de metadatos, agregue el artefacto Maven `imds` a su proyecto. También necesita clases para una `[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)` (o una `[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)` para la variante asíncrona) de la ruta de clases.
El siguiente XML de Maven muestra fragmentos de dependencia para usar el cliente síncrono [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)junto con la dependencia para los clientes de metadatos.
```
software.amazon.awssdk
bom
VERSION
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
url-connection-client
```
Busca en el [repositorio central de Maven](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) la última versión del artefacto `bom`.
Para usar un cliente HTTP asíncrono, sustituya el fragmento de dependencia del artefacto `url-connection-client`. Por ejemplo, el siguiente fragmento incluye la implementación. [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)
```
software.amazon.awssdk
netty-nio-client
```
## Utilizar el cliente de metadatos
### Crear una instancia de un cliente de metadatos
Puede crear una instancia de un sistema síncrono `Ec2MetadataClient` cuando solo haya una implementación de la interfaz `SdkHttpClient` en la ruta de clases. Para ello, llame al método estático `Ec2MetadataClient#create()`, como se muestra en el siguiente fragmento de código.
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
Si su aplicación tiene varias implementaciones de la interfaz `SdkHttpClient` o `SdkHttpAsyncClient`, debe especificar una implementación para que la utilice el cliente de metadatos, como se muestra en la sección [Cliente HTTP configurable](#examples-ec2-IMDS-features-http).
**nota**
Para la mayoría de los clientes de servicios, como Amazon S3, el SDK para Java añade automáticamente las implementaciones de la interfaz `SdkHttpClient` o `SdkHttpAsyncClient`. Si su cliente de metadatos usa la misma implementación, `Ec2MetadataClient#create()` funcionará. Si necesita una implementación diferente, debe especificarla al crear el cliente de metadatos.
### Enviar solicitudes
Para recuperar metadatos de la instancia, instancie la clase `EC2MetadataClient` y llame al método `get` con un parámetro de ruta que especifique la [categoría de metadatos de la instancia](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html).
En el siguiente ejemplo, se imprime el valor asociado a la clave `ami-id` de la consola.
```
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.
```
Si la ruta no es válida, el método `get` genera una excepción.
Puede reutilizar la misma instancia de cliente para varias solicitudes, pero ejecute `close` en el cliente cuando ya no sea necesario, con el fin de liberar recursos. Después de llamar al método close, la instancia de cliente ya no se puede usar.
### Analizar las respuestas
Los metadatos de la instancia EC2 se pueden generar en diferentes formatos. Los más utilizados son el texto sin formato y JSON. Los clientes de metadatos ofrecen formas de trabajar con esos formatos.
Como se muestra en el ejemplo siguiente, utilice el método `asString` para obtener los datos como una cadena Java. También puede usar el método `asList` para separar una respuesta de texto sin formato que devuelva varias líneas.
```
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List splits = response.asList();
```
Si la respuesta está en JSON, use el método `Ec2MetadataResponse#asDocument` para analizarla y convertirla en una instancia de [Document](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/Document.html), como se muestra en el fragmento de código siguiente.
```
Document fullResponse = response.asDocument();
```
Si el formato de los metadatos no está en JSON, se producirá una excepción. Si la respuesta se ha analizado correctamente, puede utilizar la [API de documentos](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) para inspeccionarla con más detalle. Consulte la [tabla de categorías de metadatos](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) de instancia para saber qué categorías de metadatos ofrecen respuestas con formato JSON.
## Configurar un cliente de metadatos
### Reintentos
Puede configurar un cliente de metadatos con un mecanismo de reintento. Si lo hace, el cliente podrá reintentar automáticamente las solicitudes que no puedan completarse por motivos inesperados. De forma predeterminada, el cliente lo vuelve a intentar tres veces en caso de una solicitud fallida, con un tiempo de retroceso exponencial entre intentos.
Si su caso de uso requiere un mecanismo de reintento diferente, puede personalizar el cliente mediante el método `retryPolicy` de su generador. Por ejemplo, el siguiente ejemplo muestra un cliente síncrono configurado con un retraso fijo de dos segundos entre intentos y cinco reintentos.
```
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
.backoffStrategy(fixedBackoffStrategy))
.build();
```
Hay varios [BackoffStrategies](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/backoff/package-summary.html)que puede usar con un cliente de metadatos.
También puede inhabilitar por completo el mecanismo de reintento, como se muestra en el siguiente fragmento de código.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(Ec2MetadataRetryPolicy.none())
.build();
```
El uso de `Ec2MetadataRetryPolicy#none()` desactiva la política de reintentos predeterminada para que el cliente de metadatos no efectúe reintentos.
### Versión de IP
De forma predeterminada, un cliente de metadatos usa el IPV4 punto final en`http://169.254.169.254`. Para cambiar el cliente y usar la IPV6 versión, utilice el `endpoint` método `endpointMode` o el del generador. Si se llaman ambos métodos en el constructor se produce una excepción.
En los ejemplos siguientes se muestran ambas IPV6 opciones.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
```
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpoint(URI.create("http://[fd00:ec2::254]"))
.build();
```
## Características principales de
### Cliente asíncrono
Para utilizar la versión no bloqueante del cliente, instancie una instancia de la clase `Ec2MetadataAsyncClient`. El código del siguiente ejemplo crea un cliente asíncrono con la configuración predeterminada y utiliza el método `get` para recuperar el valor de la clave `ami-id`.
```
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture response = asyncClient.get("/latest/meta-data/ami-id");
```
El valor de `java.util.concurrent.CompletableFuture` devuelto por el método `get` se completa cuando se devuelve la respuesta. En el ejemplo siguiente, se imprimen los metadatos `ami-id` en la consola.
```
response.thenAccept(metadata -> System.out.println(metadata.asString()));
```
### Cliente HTTP configurable
El generador de cada cliente de metadatos tiene un método `httpClient` que puede utilizar para proporcionar un cliente HTTP personalizado.
El ejemplo siguiente muestra el código para una instancia `UrlConnectionHttpClient` personalizada.
```
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.
```
En el ejemplo siguiente, se muestra el código de una instancia `NettyNioAsyncHttpClient` personalizada con un cliente de metadatos asíncrono.
```
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.
```
El tema [Configure los clientes HTTP en el AWS SDK for Java 2.x](http-configuration.md) de esta guía proporciona detalles sobre cómo configurar los clientes de HTTP disponibles en el SDK para Java.
### Almacenamiento en caché de tokens
Como los metadatos que utilizan los clientes IMDSv2, todas las solicitudes están asociadas a una sesión. Una sesión se define mediante un token que tiene una caducidad, que el cliente de metadatos administra en su lugar. Cada solicitud de metadatos reutiliza automáticamente el token hasta que caduque.
De forma predeterminada, un token dura seis horas (21 600 segundos). Le recomendamos que mantenga el time-to-live valor predeterminado, a menos que su caso de uso específico requiera una configuración avanzada.
Si es necesario, configure la duración utilizando el método de generador `tokenTtl`. Por ejemplo, el código del siguiente fragmento crea un cliente con una duración de sesión de cinco minutos.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.tokenTtl(Duration.ofMinutes(5))
.build();
```
Si omite llamar al método `tokenTtl` en el generador, se utilizará en su lugar la duración predeterminada de 21 600.