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á.

# Alterações no utilitário de metadados do EC2 da versão 1 para a versão 2
<a name="migration-imds"></a>

Este tópico detalha as alterações no utilitário de metadados Amazon Elastic Compute Cloud (EC2) do SDK para Java da versão 1 (v1) para a versão 2 (v2).

## Alterações de alto nível
<a name="migration-imds-high-level-changes"></a>


****  

| Alteração | v1 |  v2 da  | 
| --- | --- | --- | 
|    Dependências do Maven  |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>com.amazonaws</groupId><br />            <artifactId>aws-java-sdk-bom</artifactId><br />            <version>1.12.5871</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>com.amazonaws</groupId><br />        <artifactId>aws-java-sdk-core</artifactId><br />    </dependency><br /></dependencies></pre>  |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>software.amazon.awssdk</groupId><br />            <artifactId>bom</artifactId><br />            <version>2.27.212</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>software.amazon.awssdk</groupId><br />        <artifactId>imds</artifactId><br />    </dependency><br />    <dependency><br />        <groupId>software.amazon.awssdk</groupId><br />        <artifactId>apache-client3</artifactId><br />    </dependency><br /></dependencies></pre>  | 
| Nome do pacote |  com.amazonaws.util  |  software.amazon.awssdk.imds  | 
| Abordagem de instanciação |  Use métodos de utilitário estático; sem instanciação: <pre>String localHostName = <br />           EC2MetadataUtils.getLocalHostName();</pre>  |  Use um método estático de fábrica: <pre>Ec2MetadataClient client = Ec2MetadataClient.create();</pre> Ou use uma abordagem de criador: <pre>Ec2MetadataClient client = Ec2MetadataClient.builder()<br />    .endpointMode(EndpointMode.IPV6)<br />    .build();</pre>  | 
| Tipos de clientes | Somente métodos de utilitário síncronos: EC2MetadataUtils |  Síncrono: `Ec2MetadataClient` Assíncrono: `Ec2MetadataAsyncClient`  | 

1 [Versão mais recente](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Versão mais recente](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).

3 Observe a declaração do módulo `apache-client` para v2. A V2 do utilitário de metadados do EC2 requer uma implementação da interface `SdkHttpClient` para o cliente de metadados síncronos ou da interface `SdkAsyncHttpClient` para o cliente de metadados assíncronos. A seção [Configure clientes HTTP no AWS SDK for Java 2.x](http-configuration.md) mostra a lista de clientes HTTP que você pode usar.

### Solicitar metadados
<a name="migration-imds-fetching-changes"></a>

Na v1, você deve usar métodos estáticos que não aceitem parâmetros para solicitar metadados para um recurso do EC2. Por outro lado, é necessário especificar o caminho para o recurso do EC2 como um parâmetro na v2. A tabela a seguir mostra as diferentes abordagens.


****  

| v1 |  v2 da  | 
| --- | --- | 
|  <pre>String userMetaData = EC2MetadataUtils.getUserData();</pre>  |  <pre>Ec2MetadataClient client = Ec2MetadataClient.create();<br />Ec2MetadataResponse response = <br />                client.get("/latest/user-data");<br />String userMetaData = <br />                response.asString();</pre>  | 

Consulte as [categorias de metadados da instância](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instancedata-data-categories.html) para encontrar o caminho que você precisa fornecer para solicitar uma parte dos metadados. 

**nota**  
Ao usar um cliente de metadados de instância na v2, é necessário usar o mesmo cliente para todas as solicitações para recuperação de metadados.

 

## Mudanças de comportamento
<a name="migration-imds-behavior-changes"></a>

### Dados JSON
<a name="migration-imds-behavior-json"></a>

No EC2, o serviço de metadados de instância (IMDS) em execução local exibe alguns metadados como strings formatadas em JSON. Um exemplo são os metadados dinâmicos de um [documento de identidade de instância](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-identity-documents.html).

A API da v1 contém métodos separados para cada parte dos metadados de identidade da instância, enquanto a API da v2 exibe diretamente a string JSON. Para trabalhar com a string JSON, é possível usar a [API de documento](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) para analisar a resposta e navegar pela estrutura JSON.

A tabela a seguir compara como recuperar metadados de um documento de identidade de instância na v1 e na v2.


****  

| Caso de uso | v1 |  v2 da  | 
| --- | --- | --- | 
| Recuperar a região |  <pre>InstanceInfo instanceInfo = <br />        EC2MetadataUtils.getInstanceInfo();<br />String region = instanceInfo.getRegion();</pre>  |  <pre>Ec2MetadataResponse response = <br />    client.get("/latest/dynamic/instance-identity/document");<br />Document instanceInfo = response.asDocument();<br />String region = instanceInfo.asMap().get("region").asString();</pre>  | 
| Recupere o ID da instância |  <pre>InstanceInfo instanceInfo = <br />        EC2MetadataUtils.getInstanceInfo();<br />String instanceId = instanceInfo.instanceId;</pre>  |  <pre>Ec2MetadataResponse response = <br />    client.get("/latest/dynamic/instance-identity/document");<br />Document instanceInfo = response.asDocument();<br />String instanceId = instanceInfo.asMap().get("instanceId").asString();</pre>  | 
| Recupere o tipo da instância |  <pre>InstanceInfo instanceInfo = <br />        EC2MetadataUtils.getInstanceInfo();<br />String instanceType = instanceInfo.instanceType();</pre>  |  <pre>Ec2MetadataResponse response = <br />    client.get("/latest/dynamic/instance-identity/document");<br />Document instanceInfo = response.asDocument();<br />String instanceType = instanceInfo.asMap().get("instanceType").asString();</pre>  | 

### Diferenças na resolução do endpoint
<a name="migration-imds-behavior-endpoint-res"></a>

A tabela a seguir mostra os locais que o SDK confere para resolver o endpoint para o IMDS. Os locais são listados em ordem decrescente em termos de prioridade.


****  

| v1 |  v2 da  | 
| --- | --- | 
| Propriedade do sistema: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride | Método de configuração do criador do cliente: endpoint(...) | 
| Variável de ambiente: AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT | Propriedade do sistema: aws.ec2MetadataServiceEndpoint | 
| Valor padrão: http://169.254.169.254 | Arquivo de configuração: \$1.aws/config com a configuração ec2\$1metadata\$1service\$1endpoint | 
|  | Valor associado ao endpoint-mode resolvido  | 
|  | Valor padrão: http://169.254.169.254 | 

### Resolução de endpoint na v2
<a name="migration-imds-behavior-endpoint-res2"></a>

Quando você define explicitamente um endpoint usando o criador, esse valor de endpoint tem prioridade sobre todas as outras configurações. Quando o código a seguir é executado, a propriedade do sistema `aws.ec2MetadataServiceEndpoint` e a definição do arquivo de configuração `ec2_metadata_service_endpoint` serão ignoradas, se existirem.

```
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpoint(URI.create("endpoint.to.use"))
  .build();
```

#### Modo de endpoint
<a name="migration-imds-behavior-endpoint-mode"></a>

Com a v2, você pode especificar um modo de endpoint para configurar o cliente de metadados para usar os valores de endpoint padrão para ou. IPv4 IPv6 O modo de endpoint não está disponível para a v1. O valor padrão usado para IPv4 é `http://169.254.169.254` e `http://[fd00:ec2::254]` para IPv6.

A tabela a seguir mostra as diferentes maneiras pelas quais é possível definir o modo de endpoint em ordem decrescente em termos de prioridade.


****  

|  |  | Possíveis valores | 
| --- | --- | --- | 
| Método de configuração do criador do cliente: endpointMode(...) |  <pre>Ec2MetadataClient client = Ec2MetadataClient<br />  .builder()<br />  .endpointMode(EndpointMode.IPV4)<br />  .build();</pre>  | EndpointMode.IPV4, EndpointMode.IPV6 | 
| Propriedades do sistema | aws.ec2MetadataServiceEndpointMode | IPv4, IPv6 (o uso de maiúsculas ou minúsculas não importa) | 
| Arquivo de configuração: \$1.aws/config | Configuração da ec2\$1metadata\$1service\$1endpoint | IPv4, IPv6 (o uso de maiúsculas ou minúsculas não importa) | 
| Não especificado nas formas anteriores | IPv4 é usado |  | 

#### Como o SDK resolve `endpoint` ou `endpoint-mode` na v2
<a name="migration-imds-behavior-endpoint-res2-which"></a>

1. O SDK usa o valor definido no código no criador do cliente e ignora todas as configurações externas. Como o SDK vai gerar uma exceção se `endpoint` e `endpointMode` forem chamados no criador do cliente, o SDK usará o valor do endpoint de qualquer método usado.

1. Se você não definir um valor no código, o SDK examinará a configuração externa: primeiro as propriedades do sistema e depois uma configuração no arquivo de configuração. 

   1. O SDK primeiro confere o valor de um endpoint. Se um valor for encontrado, ele será usado. 

   1. Se o SDK ainda não encontrou um valor, ele procurará as configurações do modo de endpoint.

1. Por fim, se o SDK não encontrar configurações externas e você não tiver configurado o cliente de metadados no código, o SDK usará o IPv4 valor de. `http://169.254.169.254`

### IMDSv2
<a name="migration-imds-behavior-imdsv2"></a>

O Amazon EC2 define duas abordagens para acessar os metadados da instância:
+ Serviço de metadados de instância versão 1 (IMDSv1) — abordagem de solicitação/resposta
+ Instance Metadata Service versão 2 (IMDSv2) — abordagem orientada a sessões

A tabela a seguir compara como o Java SDKs funciona com o IMDS.


****  

| v1 |  v2 da  | 
| --- | --- | 
| IMDSv2 é usado por padrão | Sempre usa IMDSv2 | 
| Tenta buscar um token de sessão para cada solicitação e retorna IMDSv1 se não conseguir obter um token de sessão | Mantém um token de sessão em um cache interno que é reutilizado para várias solicitações. | 

O SDK for Java 2.x oferece suporte IMDSv2 somente e não é compatível com o. IMDSv1

## Diferenças de configuração
<a name="migration-imds-config-diffs"></a>

A tabela a seguir lista as diferentes opções de configuração.


****  

| Configuração | v1 |  v2 da  | 
| --- | --- | --- | 
| Novas tentativas | Configuração não disponível | Configurável por meio do método do criador retryPolicy(...) | 
| HTTP | Tempo limite de conexão configurável por meio da variável de ambiente AWS\$1METADATA\$1SERVICE\$1TIMEOUT. O padrão é 1 segundo. | Configuração disponível ao transmitir um cliente HTTP para o método do criador httpClient(...). O tempo limite de conexão padrão para clientes HTTP é de 2 segundos. | 

### Exemplo de configuração de HTTP v2
<a name="migration-imds-http-conf-v2-ex"></a>

O exemplo a seguir mostra como configurar o cliente de metadados. Este exemplo configura o tempo limite de conexão e usa o cliente do Apache HTTP.

```
SdkHttpClient httpClient = ApacheHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(1))
    .build();

Ec2MetadataClient imdsClient = Ec2MetadataClient.builder()
    .httpClient(httpClient)
    .build();
```