本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # EC2 元数据实用程序从版本 1 到版本 2 的变化本主题详细介绍了 SDK for Java Amazon Elastic Compute Cloud（EC2）元数据实用程序从版本 1（v1）到版本 2（v2）的变化。 ## 高级别更改 **** | 更改 | v1 | v2 | | --- | --- | --- | | Maven 依赖项 |


    
        
            com.amazonaws
            aws-java-sdk-bom
            1.12.5871
            pom
            import
        
    


    
        com.amazonaws
        aws-java-sdk-core


    
        
            software.amazon.awssdk
            bom
            2.27.212
            pom
            import
        
    


    
        software.amazon.awssdk
        imds
    
    
        software.amazon.awssdk
        apache-client3

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

| 使用静态工厂方法：

Ec2MetadataClient client = Ec2MetadataClient.create();

或者使用生成器方法：

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();

| | 客户端类型 | 仅同步实用程序方法：EC2MetadataUtils | 同步：`Ec2MetadataClient` 异步：`Ec2MetadataAsyncClient` | 1 [最新版本](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)。2 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。 3 注意 v2 的 `apache-client` 模块声明。EC2 元数据实用程序的 V2 需要为同步元数据客户端实现 `SdkHttpClient` 接口，或为异步元数据客户端实现 `SdkAsyncHttpClient` 接口。[在中配置 HTTP 客户端 AWS SDK for Java 2.x](http-configuration.md)部分显示了您可以使用的 HTTP 客户端列表。 ### 请求元数据在 v1 中，您可以使用不接受任何参数的静态方法来请求 EC2 资源的元数据。相比之下，在 v2 中，您需要将 EC2 资源的路径指定为参数。下表显示了不同的方法。 **** | v1 | v2 | | --- | --- | |

String userMetaData = EC2MetadataUtils.getUserData();

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = 
                client.get("/latest/user-data");
String userMetaData = 
                response.asString();

| 请参阅[实例元数据类别](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instancedata-data-categories.html)，查找请求元数据时需要提供的路径。 **注意** 在 v2 中使用实例元数据客户端时，您应该针对检索元数据的所有请求使用同一客户端。 ## 行为更改 ### JSON 数据在 EC2 上，本地运行的实例元数据服务（IMDS）以 JSON 格式的字符串形式返回一些元数据。[实例身份文档](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-identity-documents.html)的动态元数据就是一个例子。 v1 API 针对每种实例身份元数据包含不同的方法，而 v2 API 会直接返回 JSON 字符串。要处理 JSON 字符串，您可以使用[文档 API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) 解析响应并浏览 JSON 结构。下表比较了在 v1 和 v2 中检索实例身份文档元数据的方式。 **** | 使用案例 | v1 | v2 | | --- | --- | --- | | 检索区域 |

InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String region = instanceInfo.getRegion();

Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String region = instanceInfo.asMap().get("region").asString();

| | 检索实例 ID |

InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String instanceId = instanceInfo.instanceId;

Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceId = instanceInfo.asMap().get("instanceId").asString();

| | 检索实例类型 |

InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String instanceType = instanceInfo.instanceType();

Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceType = instanceInfo.asMap().get("instanceType").asString();

| ### 端点解析差异下表显示了 SDK 为将端点解析到 IMDS 而检查的位置。这些位置按优先级降序列出。 **** | v1 | v2 | | --- | --- | | 系统属性：com.amazonaws.sdk.ec2MetadataServiceEndpointOverride | 客户端生成器配置方法：endpoint(...) | | 环境变量：AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT | 系统属性：aws.ec2MetadataServiceEndpoint | | 默认值：http://169.254.169.254 | Config 文件：\$1.aws/config，及 ec2\$1metadata\$1service\$1endpoint 设置 | | | 与已解析的 endpoint-mode 相关联的值 | | | 默认值：http://169.254.169.254 | ### v2 中的端点解析如果您使用生成器显式设置端点，该端点值的优先级高于所有其他设置。当以下代码执行时，`aws.ec2MetadataServiceEndpoint` 系统属性和 config 文件 `ec2_metadata_service_endpoint` 设置如果存在，将被忽略。 ``` Ec2MetadataClient client = Ec2MetadataClient .builder() .endpoint(URI.create("endpoint.to.use")) .build(); ``` #### 端点模式在 v2 中，您可以指定端点模式，将元数据客户端配置为使用或的默认端点值。 IPv4 IPv6端点模式不适用于 v1。使用的默认值为`http://169.254.169.254`和 IPv4 fo `http://[fd00:ec2::254]` r IPv6。下表按优先级降序显示了设置端点模式时可以采用的不同方法。 **** | | | 可能的值 | | --- | --- | --- | | 客户端生成器配置方法：endpointMode(...) |

Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();

| EndpointMode.IPV4, EndpointMode.IPV6 | | 系统属性 | aws.ec2MetadataServiceEndpointMode | IPv4、IPv6（大小写没有影响） | | Config 文件：\$1.aws/config | ec2\$1metadata\$1service\$1endpoint 设置 | IPv4、IPv6（大小写没有影响） | | 未在前面的方法中指定 | IPv4 被使用了 | | #### 在 v2 中，SDK 如何解析`endpoint`或`endpoint-mode` 1. SDK 使用您通过客户端生成器在代码中设置的值，并忽略任何外部设置。由于在客户端生成器上同时调用 `endpoint` 和 `endpointMode` 时，SDK 会抛出异常，因此 SDK 将使用您所用的任一方法中的端点值。 1. 如果您没有在代码中设置值，SDK 会查看外部配置；首先查找系统属性，然后是 config 文件中的设置。 1. SDK 会先检查端点值。如果找到值，则使用该值。 1. 如果 SDK 仍未找到值，则会查找端点模式设置。 1. 最后，如果 SDK 未找到任何外部设置，并且您尚未在代码中配置元数据客户端，则 SDK 将使用 IPv4 值`http://169.254.169.254`。 ### IMDSv2 Amazon EC2 定义了两种访问实例元数据的方法： + 实例元数据服务版本 1 (IMDSv1)-请求/响应方法 + 实例元数据服务版本 2 (IMDSv2)-面向会话的方法下表比较了 Java SDKs 如何与 IMDS 配合使用。 **** | v1 | v2 | | --- | --- | | IMDSv2 默认情况下使用 | 始终使用 IMDSv2 | | 尝试为每个请求获取会话令牌， IMDSv1 如果无法获取会话令牌，则回退到会话令牌 | 将会话令牌保存在内部缓存中，该令牌可重复用于多个请求 | 适用于 Java 的 SDK 2.x 仅支持 IMDSv2 ，不能回退到。 IMDSv1 ## 配置差异下表列出了不同的配置选项。 **** | 配置 | v1 | v2 | | --- | --- | --- | | 重试 | 配置不可用 | 可通过生成器方法 retryPolicy(...) 配置 | | HTTP | 连接超时可通过 AWS\$1METADATA\$1SERVICE\$1TIMEOUT 环境变量配置。默认值为 1 秒。 | 通过将 HTTP 客户端传递给生成器方法 httpClient(...) 即可进行配置。HTTP 客户端的默认连接超时为 2 秒。 | ### v2 HTTP 配置示例以下示例演示了如何配置元数据客户端。此示例配置连接超时并使用 Apache HTTP 客户端。 ``` SdkHttpClient httpClient = ApacheHttpClient.builder() .connectionTimeout(Duration.ofSeconds(1)) .build(); Ec2MetadataClient imdsClient = Ec2MetadataClient.builder() .httpClient(httpClient) .build(); ```