现在，您可以使用 适用于 Java 2.x 的 亚马逊云科技 开发工具包 轻松检索 亚马逊弹性计算云 （亚马逊 EC2）实例的实例元数据！我们很高兴地宣布，适用于 Java 的 亚马逊云科技 开发工具包 2.x（版本 2.19.29 或更高版本）中新的 Java SDK EC2 实例元数据客户端已正式上线。您可以使用此新功能访问基于 JVM 的应用程序中的本地 EC2 实例元数据。

适用于 Java 2.x 的 亚马逊云科技 开发工具包现在有两个新的客户端类可用：一个用于阻塞操作的同步客户端和一个用于非阻塞操作的异步客户端。新客户端使用 IMDSv2（实例元数据服务 v2） ，它使用面向会话的请求。

这篇博客文章展示了如何使用新客户端在应用程序中检索元数据，并更深入地介绍了一些新功能。

入门

要使用 EC2 实例元数据客户端，请先将 依赖 项 添加到您的项目中。

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>imds</artifactId> 
    <version>${imds.version}</version> 
</dependency>

你还需要类路径上的 sdkHttpClient （或异步变体的 sdka SynchttpClient）的类， 因为元数据客户端需要它。您可以在 “可配置 HTTP 客户端” 部分了解更多详细信息。

正在发送请求

要检索实例元数据，只需将 EC2MetadataClient 类实例化，然后使用指定实例元数据类别的路径参数调用 get 方法即可。 以下示例会将与 ami-id 密钥关联的值打印到控制台。

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

如果指定的路径无效，则 get 方法会抛出异常。

请记住，您无需为每个请求创建新客户端。您可以将同一个实例重复用于多个请求，但请记住在不再需要时通过在客户端实例上调用 close 方法来 关闭客户端。一旦调用 cl os e 方法，就不能再使用客户端 方法。

解析响应

EC2 实例元数据可以以不同的格式输出。由于纯文本和 JSON 是最常用的格式，因此元数据客户端提供了使用这些格式的简便方法。

如以下示例所示，使用 asString 方法将数据作为简单的 Java 字符串获取。您也可以使用 asList 方法分隔返回多行的纯文本响应。

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List<String> splits = response.asList();

如果响应采用 JSON 格式，请使用 ec2MetadataResponse #asDocument 方法将 JSON 响应解析为文档实例。

Document fullResponse = response.asDocument();

如果元数据的格式不是 JSON，则客户端将抛出异常。如果成功解析了响应，则 可以使用 文档 API 来更详细地检查响应。查阅 实例元数据类别表 ，了解哪些元数据类别返回 JSON 格式的响应。

配置 EC2 元数据客户端

您可以使用 重试策略 配置 EC2 实例元数据客户端。重试允许客户端自动重试因意外原因而失败的请求。默认情况下，客户端将对失败的请求重试 3 次，两次尝试之间的退避时间呈指数级增长。

由于大多数应用程序只需要默认的重试配置，因此我们建议您保留项目的默认重试策略。但是，如果您的用例需要独特的配置，则修改重试机制非常容易。以下示例显示了在尝试和 5 次重试之间配置了固定延迟的同步客户端。

BackoffStrategy fixedBackoffStrategy = 
    FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .retryPolicy(retryPolicyBuilder -> 
                         retryPolicyBuilder.numRetries(5)
                                           .backoffStrategy(fixedBackoffStrategy))
                     .build();

您也可以使用以下代码段完全禁用重试机制。

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .retryPolicy(Ec2MetadataRetryPolicy.none())
                     .build(); 

使用 ec2metadataretryPolicy.none () 将确保不尝试重试。适用于 Java 的 亚马逊云科技 开发工具包 v2.x 中 已经有许多不同的 BackoffSt rategies 可供您与元数据客户端一起使用。

主要特点

异步客户端

要使用非阻塞版本的客户端，请实例化 EC2MetadataAsyncClient 类的实例。以下示例中的代码使用默认设置创建了异步客户端，并使用 get 方法检索 ami-id 密 钥的值。

Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");

当返回响应时，get 方法 返回的 java.util.concurrent.completableFuture 即会完成。 以下示例将 ami-id 元数据打印到控制台。

response.thenAccept(metadata -> System.out.println(metadata.asString()));

如果您的工作负载不需要异步编程，请改用同步 EC2MetadataClient。

可配置 HTTP 客户端

以下示例说明如何自定义 URLConnectionHttpClient 实例或 n ettynioAsynchttpClient 实例，并将其与相应的同步或异步元数据客户端 一起 使用。

SdkHttpClient httpClient =
    UrlConnectionHttpClient.builder()
    // your custom configuration here
    .build();
Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .httpClient(httpClient)
                     .build();

SdkAsyncHttpClient asyncHttpClient =
    NettyNioAsyncHttpClient.builder()
    // your custom configuration here
    .build();
Ec2MetadataAsyncClient asyncClient=
    Ec2MetadataAsyncClient.builder()
                          .httpClient(asyncHttpClient)
                          .build();

使用 HTTP 客户端配置与 HTTP 请求相关的常用选项，例如超时或代理选项。要配置和使用 HTTP 客户端，请将工件添加到您的项目依赖项中。适用于 Java 的 亚马逊云科技 开发工具包 v2.x 中提供了同步 HTTP 客户端和异步 HTTP 客户端的其他实现。它们都适用于元数据客户端。

代币缓存

所有请求都与会话相关联，因为新的 EC2 实例元数据客户端使用 IMDSv2。会话由已过期的令牌定义，由元数据客户端管理。每个元数据请求都会自动重复使用令牌，直到它过期。

默认情况下，令牌将持续 6 小时（21,600 秒），但该持续时间可使用 TokenTTL 生成器方法进行配置。例如，以下代码片段创建了一个会话时长为 5 分钟的客户端。

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .tokenTtl(Duration.ofMinutes(5))
                     .build();

如果您省略在生成器上调用 t okenTTL 方法，则将改用默认值 21,600。除非您的特定用例需要高级配置，否则我们建议您保留默认的生存时间值。

结论

在这篇博客文章中，我们展示了适用于 Java 的 亚马逊云科技 开发工具包 v2.x 中提供的新 Java SDK EC2 实例元数据客户端的关键功能。我们提供了示例来说明如何使用这些客户端和检索 EC2 实例元数据。请在此博客上发表评论或通过 GitHub 联系我们，告诉我们您如何使用 EC2 的 IMDS（实例元数据服务）和企业 Java 应用程序中的新客户端！如果你有改进的想法，可以毫不犹豫地提出问题或拉取请求。您也可以参阅 Java (v2) SDK 开发者指南 和 API 参考资料 ，了解有关使用这些客户端的更多信息。