As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Trabalhar com metadados da instância do Amazon EC2
Um cliente Java SDK para o Amazon EC2 Instance Metadata Service (cliente de metadados) permite que seus aplicativos acessem metadados em sua instância EC2 local. O cliente de metadados trabalha com a instância local do [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)(Instance Metadata Service v2) e usa solicitações orientadas à sessão.
Duas classes de cliente estão disponíveis no SDK. O `[Ec2MetadataClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataClient.html)` síncrono serve para operações de bloqueio e o [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) é para casos de uso assíncronos e sem bloqueio.
## Conceitos básicos
Para usar o cliente de metadados, adicione o artefato `imds` Maven ao seu projeto. Você também precisa de classes para um `[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)` (ou um `[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)` para a variante assíncrona) no caminho de classe.
O XML do Maven a seguir mostra trechos de dependência para usar o síncrono [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)junto com a dependência para clientes de metadados.
```
software.amazon.awssdk
bom
VERSION
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
url-connection-client
```
Pesquise no [repositório central do Maven](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) a versão mais recente do artefato `bom`.
Para usar um cliente HTTP assíncrono, substitua o trecho de dependência do artefato `url-connection-client`. Por exemplo, o trecho a seguir traz a [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)implementação.
```
software.amazon.awssdk
netty-nio-client
```
## Usar o cliente de metadados
### Instanciar um cliente de metadados
Você pode instanciar uma instância de um `Ec2MetadataClient` síncrono quando somente uma implementação da interface `SdkHttpClient` está presente no caminho de classe. Para fazer isso, chame o método estático `Ec2MetadataClient#create()`, conforme mostrado no trecho a seguir.
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
Se seu aplicativo tiver várias implementações da interface `SdkHttpClient` ou `SdkHttpAsyncClient`, você deverá especificar uma implementação para o cliente de metadados usar, conforme mostrado na seção [Cliente HTTP configurável](#examples-ec2-IMDS-features-http).
**nota**
Para a maioria dos clientes de serviços, como o Amazon S3, o SDK for Java adiciona automaticamente implementações da interface `SdkHttpClient` ou `SdkHttpAsyncClient`. Se seu cliente de metadados usar a mesma implementação, o `Ec2MetadataClient#create()` funcionará. Se você precisar de uma implementação diferente, deverá especificá-la ao criar o cliente de metadados.
### Envie solicitações
Para recuperar os metadados da instância, instancie a classe `EC2MetadataClient` e chame o método `get` com um parâmetro de caminho que especifica a [categoria de metadados da instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html).
O exemplo a seguir imprime o valor associado à chave `ami-id` no 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 o caminho não for válido, o método `get` gerará uma exceção.
Reutilize a mesma instância do cliente para várias solicitações, mas chame `close` no cliente quando não for mais necessário liberar recursos. Depois que o método de fechamento é chamado, a instância do cliente não pode mais ser usada.
### Analisar respostas
Os metadados da instância EC2 podem ser gerados em formatos diferentes. Texto sem formatação e JSON são os formatos mais usados. Os clientes de metadados oferecem formas de trabalhar com esses formatos.
Como mostra o exemplo a seguir, use o método `asString` para obter os dados como uma string Java. Você também pode usar o método `asList` para separar uma resposta de texto sem formatação que retorna várias linhas.
```
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List splits = response.asList();
```
Se a resposta estiver em JSON, use o método `Ec2MetadataResponse#asDocument` para analisar a resposta JSON em uma instância de [Documento](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/Document.html), conforme mostrado no trecho de código a seguir.
```
Document fullResponse = response.asDocument();
```
Uma exceção será lançada se o formato dos metadados não estiver em JSON. Se a resposta for analisada com sucesso, você poderá usar a [API do documento](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) para inspecionar a resposta com mais detalhes. Consulte o [gráfico de categorias de metadados](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) da instância para saber quais categorias de metadados fornecem respostas em formato JSON.
## Configurar um cliente de metadados
### Novas tentativas
Você pode configurar um cliente de metadados com um mecanismo de repetição. Se você fizer isso, o cliente poderá repetir automaticamente as solicitações que falharem por motivos inesperados. Por padrão, o cliente tenta novamente três vezes em uma solicitação com falha, com um tempo de recuo exponencial entre as tentativas.
Se seu caso de uso exigir um mecanismo de repetição diferente, você poderá personalizar o cliente usando o método `retryPolicy` em seu construtor. Por exemplo, o exemplo a seguir mostra um cliente síncrono configurado com um atraso fixo de dois segundos entre as tentativas e cinco tentativas de repetição.
```
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
.backoffStrategy(fixedBackoffStrategy))
.build();
```
Há várias [BackoffStrategies](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/backoff/package-summary.html)que você pode usar com um cliente de metadados.
Você também pode desativar totalmente o mecanismo de repetição, como mostra o trecho a seguir.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(Ec2MetadataRetryPolicy.none())
.build();
```
O uso do `Ec2MetadataRetryPolicy#none()` desativa a política de repetição padrão para que o cliente de metadados não tente fazer novas tentativas.
### Versão IP
Por padrão, um cliente de metadados usa o IPV4 endpoint em. `http://169.254.169.254` Para alterar o cliente para usar a IPV6 versão, use o `endpoint` método `endpointMode` ou o do construtor. Uma exceção ocorre se os dois métodos forem chamados no construtor.
Os exemplos a seguir mostram as duas IPV6 opções.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
```
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpoint(URI.create("http://[fd00:ec2::254]"))
.build();
```
## Recursos principais do
### Cliente assíncrono
Para usar a versão sem bloqueio do cliente, instancie uma instância da classe `Ec2MetadataAsyncClient`. O código no exemplo a seguir cria um cliente assíncrono com configurações padrão e usa o método `get` para recuperar o valor da chave `ami-id`.
```
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture response = asyncClient.get("/latest/meta-data/ami-id");
```
O `java.util.concurrent.CompletableFuture` retornado pelo método `get` é concluído quando a resposta retorna. O exemplo a seguir imprime os metadados `ami-id` no console.
```
response.thenAccept(metadata -> System.out.println(metadata.asString()));
```
### Cliente HTTP configurável
O construtor de cada cliente de metadados tem um método `httpClient` que você pode usar para fornecer um cliente HTTP personalizado.
O exemplo a seguir mostra o código para uma instância personalizada do `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.
```
O exemplo a seguir mostra o código de uma instância personalizada do `NettyNioAsyncHttpClient` com um cliente de metadados assí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.
```
O tópico [Configure clientes HTTP no AWS SDK for Java 2.x](http-configuration.md) deste guia fornece detalhes sobre como configurar os clientes HTTP que estão disponíveis no SDK para Java.
### Armazenamento em cache de tokens
Como os metadados usados pelos clientes IMDSv2, todas as solicitações são associadas a uma sessão. Uma sessão é definida por um token que tem uma expiração, que o cliente de metadados gerencia para você. Cada solicitação de metadados reutiliza automaticamente o token até que ele expire.
Por padrão, um token dura seis horas (21.600 segundos). Recomendamos que você mantenha o time-to-live valor padrão, a menos que seu caso de uso específico exija configuração avançada.
Se necessário, configure a duração usando o método `tokenTtl` do construtor. Por exemplo, o código no trecho a seguir cria um cliente com duração de sessão de cinco minutos.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.tokenTtl(Duration.ofMinutes(5))
.build();
```
Se você omitir a chamada do método `tokenTtl` no construtor, a duração padrão de 21.600 será usada em vez disso.