翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# EC2 メタデータユーティリティのバージョン 1 からバージョン 2 への変更
<a name="migration-imds"></a>

このトピックでは、SDK for Java Amazon Elastic Compute Cloud (EC2) メタデータユーティリティのバージョン 1 (v1) からバージョン 2 (v2) への変更について詳しく説明します。

## 高レベル変更
<a name="migration-imds-high-level-changes"></a>


****  

| 変更 | v1 |  v2 | 
| --- | --- | --- | 
|    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>  | 
| パッケージ名 |  com.amazonaws.util  |  software.amazon.awssdk.imds  | 
| インスタンス化のアプローチ |  静的ユーティリティメソッドを使用し、インスタンス化を行わない。 <pre>String localHostName = <br />           EC2MetadataUtils.getLocalHostName();</pre>  |  静的ファクトリメソッドを使用する。 <pre>Ec2MetadataClient client = Ec2MetadataClient.create();</pre> または、ビルダーのアプローチを使用する。 <pre>Ec2MetadataClient client = Ec2MetadataClient.builder()<br />    .endpointMode(EndpointMode.IPV6)<br />    .build();</pre>  | 
| クライアントのタイプ | 同期専用ユーティリティメソッド: 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 クライアントのリストが表示されています。

### メタデータのリクエスト
<a name="migration-imds-fetching-changes"></a>

v1 では、パラメータを受け付けない静的メソッドを使用して EC2 リソースのメタデータをリクエストします。これとは対照的に、v2 では EC2 リソースへのパスをパラメータとして指定する必要があります。次の表は、それぞれのアプローチの違いをまとめたものです。


****  

| v1 |  v2 | 
| --- | --- | 
|  <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>  | 

[インスタンスメタデータのカテゴリ](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instancedata-data-categories.html)を参照して、メタデータをリクエストするために指定する必要のあるパスを見つけてください。

**注記**  
v2 でインスタンスメタデータクライアントを使用するときは、メタデータを取得するすべてのリクエストに同じクライアントを使用することを心がける必要があります。

 

## 動作の変更
<a name="migration-imds-behavior-changes"></a>

### JSON データ
<a name="migration-imds-behavior-json"></a>

EC2 では、ローカルで実行されているインスタンスメタデータサービス (IMDS) が一部のメタデータを JSON 形式の文字列として返します。その一例が、[インスタンス ID ドキュメント](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-identity-documents.html)の動的メタデータです。

v1 API にはインスタンス ID メタデータごとに個別のメソッドが含まれていますが、v2 API は JSON 文字列を直接返します。JSON 文字列を処理するには、[ドキュメント API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) を使用して応答を解析し、JSON 構造に移動します。

次の表は、v1 と v2 でインスタンス ID ドキュメントのメタデータを取得する方法を比較したものです。


****  

| ユースケース | v1 |  v2 | 
| --- | --- | --- | 
| リージョンを取得する |  <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>  | 
| インスタンス ID を取得する |  <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>  | 
| インスタンスタイプを取得する |  <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>  | 

### エンドポイント解決の違い
<a name="migration-imds-behavior-endpoint-res"></a>

次の表は、エンドポイントを IMDS に対して解決するために SDK がチェックする場所を示しています。場所は優先度の高い順にリストされています。


****  

| 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 のエンドポイント解決
<a name="migration-imds-behavior-endpoint-res2"></a>

ビルダーを使用してエンドポイントを明示的に設定すると、そのエンドポイント値が他のすべての設定よりも優先されます。次のコードを実行すると、`aws.ec2MetadataServiceEndpoint` システムプロパティと設定ファイル `ec2_metadata_service_endpoint` の設定が存在しても無視されます。

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

#### エンドポイントモード
<a name="migration-imds-behavior-endpoint-mode"></a>

v2 では、エンドポイントモードを指定して、メタデータクライアントが IPv4 または IPv6 のデフォルトのエンドポイント値を使用するように設定できます。v1 ではエンドポイントモードを使用できません。IPv4 で使用されるデフォルト値は `http://169.254.169.254` で、IPv6 では `http://[fd00:ec2::254]` です。

次の表に、エンドポイントモードを設定するさまざまな方法を優先順位の高い順に示します。


****  

|  |  | 使用できる値 | 
| --- | --- | --- | 
| クライアントビルダーの設定方法: endpointMode(...) |  <pre>Ec2MetadataClient client = Ec2MetadataClient<br />  .builder()<br />  .endpointMode(EndpointMode.IPV4)<br />  .build();</pre>  | EndpointMode.IPV4, EndpointMode.IPV6 | 
| システムプロパティ | aws.ec2MetadataServiceEndpointMode | IPv4、IPv6 (大文字と小文字は区別されません) | 
| 設定ファイル: \$1.aws/config  | ec2\$1metadata\$1service\$1endpoint の設定 | IPv4、IPv6 (大文字と小文字は区別されません) | 
| 以前の方法では未指定 | IPv4 が使用される |  | 

#### v2 での SDK による `endpoint` または `endpoint-mode` の解決方法
<a name="migration-imds-behavior-endpoint-res2-which"></a>

1. SDK は、クライアントビルダーのコードで設定した値を使用し、外部設定は無視します。`endpoint` および `endpointMode` が両方ともクライアントビルダーで呼び出されると SDK は例外をスローするため、SDK はユーザーが使用するメソッドのエンドポイント値を使用します。

1. コードで値を設定しない場合、SDK は外部設定を調べます。最初にシステムプロパティを検索し、次に設定ファイル内の設定を検索します。

   1. SDK は最初にエンドポイント値をチェックします。値が見つかると、その値が使用されます。

   1. 値が見つからない場合は、SDK はエンドポイントモード設定を探します。

1. 最後に、SDK が外部設定を見つけられず、コードでメタデータクライアントを設定していない場合は、SDK は IPv4 の値の `http://169.254.169.254` を使用します。

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

Amazon EC2 では、インスタンスメタデータにアクセスするための 2 つのアプローチを定義しています。
+ インスタンスメタデータサービスバージョン 1 (IMDSv1) – リクエスト/レスポンスアプローチ
+ インスタンスメタデータサービスバージョン 2 (IMDSv2) – セッション指向アプローチ

次の表は、Java SDK が IMDS をどのように使用するかを比較したものです。


****  

| v1 |  v2 | 
| --- | --- | 
| IMDSv2 がデフォルトで使用される | IMDSv2 を常に使用する | 
| リクエストごとにセッショントークンの取得を試み、セッショントークンの取得に失敗した場合は IMDSv1 にフォールバックする | セッショントークンを内部キャッシュに保持し、複数のリクエストで再利用する | 

SDK for Java 2.x は IMDSv2 のみをサポートしており、IMDSv1 にはフォールバックしません。

## 設定の違い
<a name="migration-imds-config-diffs"></a>

以下の表にさまざまな設定オプション一覧表示します。


****  

| 設定 | v1 |  v2 | 
| --- | --- | --- | 
| 再試行 | 設定不可 | ビルダーメソッド retryPolicy(...) で設定可能  | 
| HTTP | 接続タイムアウトは AWS\$1METADATA\$1SERVICE\$1TIMEOUT 環境変数で設定可能。デフォルト値は 1 秒です。 | HTTP クライアントを httpClient(...) ビルダーメソッドに渡すことで設定可能。HTTP クライアントのデフォルトの接続タイムアウトは 2 秒です。 | 

### v2 の HTTP 設定の例
<a name="migration-imds-http-conf-v2-ex"></a>

以下の例に、メタデータクライアントの設定方法を示します。この例では、接続タイムアウトを設定し、Apache HTTP クライアントを使用します。

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

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