翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon EC2 インスタンスメタデータを操作する
Amazon EC2 インスタンスメタデータサービスの Java SDK クライアント (メタデータクライアント) を使用すると、アプリケーションはローカル EC2 インスタンスのメタデータにアクセスできます。メタデータクライアントは [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) のローカルインスタンス (インスタンスメタデータサービス v2) と連携し、セッション指向のリクエストを使用します。
SDK には 2 つのクライアントクラスがあります。同期 `[Ec2MetadataClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataClient.html)` はブロッッキングオペレーション用で、[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) は非同期、ノンブロッキングのユースケース用です。
## はじめに
メタデータクライアントを使用するには、`imds` Maven アーティファクトをプロジェクトに追加します。クラスパスには `[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)` (または非同期バリアントの場合は `[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)`) のクラスも必要です。
次の Maven XML は、同期 [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) を使用するための依存関係のスニペットと、メタデータクライアントの依存関係を示しています。
```
software.amazon.awssdk
bom
VERSION
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
url-connection-client
```
[Maven central リポジトリ](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)で `bom` アーティファクトの最新バージョンを検索してください。
非同期 HTTP クライアントを使用するには、`url-connection-client` アーティファクトの依存関係スニペットを置き換えてください。たとえば、次のスニペットでは [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) の実装が取り込まれています。
```
software.amazon.awssdk
netty-nio-client
```
## メタデータクライアントを使用する
### メタデータクライアントをインスタンス化する
クラスパスに `SdkHttpClient` インタフェースの実装が 1 つしかない場合は、同期 `Ec2MetadataClient` のインスタンスをインスタンス化できます。そのためには、以下のスニペットに示すように静的 `Ec2MetadataClient#create()` メソッドを呼び出します。
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
アプリケーションに `SdkHttpClient` または `SdkHttpAsyncClient` インターフェースの実装が複数ある場合は、[設定可能な HTTP クライアント](#examples-ec2-IMDS-features-http) セクションに示されているように、メタデータクライアントが使用する実装を指定する必要があります。
**注記**
Amazon S3 などのほとんどのサービスクライアントでは、SDK for Java は `SdkHttpClient` または `SdkHttpAsyncClient` インターフェイスの実装を自動的に追加します。メタデータクライアントが同じ実装を使用している場合は、`Ec2MetadataClient#create()` は問題なく動作します。別の実装が必要な場合は、メタデータクライアントの作成時にその実装を指定する必要があります。
### リクエストを送信する
インスタンスメタデータを取得するには、`EC2MetadataClient` クラスをインスタンス化し、[インスタンスメタデータカテゴリ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html)を指定するパスパラメータを使用して `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` 同じクライアントインスタンスを複数のリクエストに再利用し、リソースを解放する必要がなくなったらクライアントを呼び出します。クローズメソッドが呼び出されると、クライアントインスタンスは使用できなくなります。
### レスポンスを解析する
EC2 インスタンスメタデータはさまざまな形式で出力できます。プレーンテキストと JSON が最も一般的に使用される形式です。メタデータクライアントには、これらの形式を処理する方法が用意されています。
次の例に示すように、`asString` メソッドを使用してデータを Java 文字列として取得します。`asList` メソッドを使用して、複数行を返すプレーンテキストレスポンスを区切ることもできます。
```
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List splits = response.asList();
```
レスポンスが JSON の場合は、次のコードスニペットに示すように、`Ec2MetadataResponse#asDocument` メソッドを使用して JSON レスポンスを解析して[ドキュメント](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/Document.html)インスタンスにします。
```
Document fullResponse = response.asDocument();
```
メタデータの形式が JSON でない場合は例外が発生します。レスポンスが正常に解析されたら、[ドキュメント API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) を使用してレスポンスをより詳細に調べることができます。JSON 形式のレスポンスを返すメタデータカテゴリについては、インスタンスの「[metadata category chart](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html)」を参照してください。
## メタデータクライアントを設定する
### 再試行
メタデータクライアントには再試行メカニズムを設定できます。そうすることで、クライアントは予期しない理由で失敗したリクエストを自動的に再試行できます。デフォルトでは、クライアントは失敗したリクエストに対し、エクスポネンシャルバックオフ時間を置いて 3 回再試行します。
ユースケースで別の再試行メカニズムが必要な場合は、ビルダーの `retryPolicy` メソッドを使用してクライアントをカスタマイズできます。たとえば、次の例は、試行間隔が 2 秒、再試行が 5 回になるように設定された同期クライアントを示しています。
```
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
.backoffStrategy(fixedBackoffStrategy))
.build();
```
メタデータクライアントで使用できる [BackoffStrategies](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/backoff/package-summary.html) はいくつかあります。
次のスニペットに示すように、リトライメカニズムを完全に無効にすることもできます。
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(Ec2MetadataRetryPolicy.none())
.build();
```
`Ec2MetadataRetryPolicy#none()` を使用すると、メタデータクライアントが再試行しないように、デフォルトの再試行ポリシーが無効になります。
### IP バージョン
デフォルトでは、メタデータクライアントは `http://169.254.169.254` の IPV4 エンドポイントを使用します。IPV6 バージョンを使用するようにクライアントを変更するには、ビルダーの `endpointMode` または `endpoint` メソッドを使用します。ビルダーで両方のメソッドが呼び出されると、例外が発生します。
次の例は、両方の IPV6 オプションを示しています。
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
```
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpoint(URI.create("http://[fd00:ec2::254]"))
.build();
```
## 主な特徴
### 非同期クライアント
ノンブロッキングバージョンのクライアントを使用するには、`Ec2MetadataAsyncClient` クラスのインスタンスをインスタンス化します。次の例のコードは、デフォルト設定で非同期クライアントを作成し、`get` メソッドを使用して `ami-id` キーの値を取得します。
```
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture response = asyncClient.get("/latest/meta-data/ami-id");
```
`get` メソッドから返された `java.util.concurrent.CompletableFuture` は、レスポンスが返された時点で完了します。次の例では、`ami-id` メタデータをコンソールに出力します。
```
response.thenAccept(metadata -> System.out.println(metadata.asString()));
```
### 設定可能な HTTP クライアント
各メタデータクライアントのビルダーには、カスタマイズされた HTTP クライアントを提供するために使用できる `httpClient` メソッドがあります。
次の例はカスタム `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.
```
次の例は、非同期メタデータクライアントを使用するカスタム `NettyNioAsyncHttpClient` インスタンスのコードを示しています。
```
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.
```
このガイドの [で HTTP クライアントを設定する AWS SDK for Java 2.x](http-configuration.md) トピックでは、SDK for Java で使用可能な HTTP クライアントの設定方法について詳しく説明しています。
### トークンキャッシュ
メタデータクライアントは IMDSv2 を使用するため、すべてのリクエストはセッションに関連付けられます。セッションは、メタデータクライアントが管理する有効期限のあるトークンによって定義されます。メタデータをリクエストするたびに、トークンは有効期限が切れるまで自動的に再利用されます。
デフォルトでは、トークンは 6 時間 (21,600 秒) 持続します。特定のユースケースで高度な設定が必要でない限り、有効期間をデフォルト値のままにしておくことをお勧めします。
必要に応じて、`tokenTtl` ビルダーメソッドを使用して期間を設定します。たとえば、次のスニペットのコードでは、セッション期間が 5 分のクライアントを作成します。
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.tokenTtl(Duration.ofMinutes(5))
.build();
```
ビルダーで `tokenTtl` メソッドを呼び出さない場合は、代わりにデフォルトの継続時間である 21,600 が使用されます。