本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# EC2 中繼資料公用程式從第 1 版變更為第 2 版
<a name="migration-imds"></a>

本主題詳細說明適用於 Java 的 SDK 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`界面。 EC2 [在 中設定 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 格式字串傳回一些中繼資料。其中一個範例是[執行個體身分文件](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 | 
| --- | --- | --- | 
| 擷取區域 |  <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>

下表顯示 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 中的端點解析
<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://[fd00:ec2::254]` IPv6 的 `http://169.254.169.254`和 。 IPv6

下表顯示您可以依遞減優先順序設定端點模式的不同方式。


****  

|  |  | 可能的值 | 
| --- | --- | --- | 
| 用戶端建置器組態方法： 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 `endpoint-mode`中解析 `endpoint`或
<a name="migration-imds-behavior-endpoint-res2-which"></a>

1. SDK 會使用您在用戶端建置器程式碼中設定的值，並忽略任何外部設定。由於軟體開發套件會在用戶端建置器上`endpointMode`同時呼叫 `endpoint`和 時擲回例外狀況，因此軟體開發套件會使用您使用任何方法的端點值。

1. 如果您未在程式碼中設定值，軟體開發套件會先尋找外部組態，然後再尋找組態檔案中的設定。

   1. 開發套件會先檢查端點值。如果找到值，則會使用該值。

   1. 如果軟體開發套件仍然找不到值，軟體開發套件會尋找端點模式設定。

1. 最後，如果軟體開發套件找不到外部設定，而且您尚未在程式碼中設定中繼資料用戶端，則軟體開發套件會使用 的 IPv4 值`http://169.254.169.254`。

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

Amazon EC2 定義兩種存取執行個體中繼資料的方法：
+ 執行個體中繼資料服務第 1 版 (IMDSv1) – 請求/回應方法
+ 執行個體中繼資料服務第 2 版 (IMDSv2) – 工作階段導向方法

下表比較 Java SDKs如何使用 IMDS。


****  

| v1 |   v2 | 
| --- | --- | 
| 根據預設會使用 IMDSv2  | 一律使用 IMDSv2 | 
| 嘗試為每個請求擷取工作階段字符，如果無法擷取工作階段字符，則會回到 IMDSv1  | 將工作階段字符保留在針對多個請求重複使用的內部快取中 | 

適用於 Java 的 SDK 2.x 僅支援 IMDSv2，不會回復為 IMDSv1。

## 組態差異
<a name="migration-imds-config-diffs"></a>

下表列出不同的組態選項。


****  

| Configuration | 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();
```