EC2 中繼資料公用程式從第 1 版變更為第 2 版 - AWS SDK for Java 2.x
高階變更行為變更組態差異

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

EC2 中繼資料公用程式從第 1 版變更為第 2 版

本主題詳細說明適用於 Java 的 SDK Amazon Elastic Compute Cloud (EC2) 中繼資料公用程式中從第 1 版 (v1) 到第 2 版 (v2) 的變更。

高階變更

變更 v1 v2

Maven 相依性

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.5871</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-core</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.27.212</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>imds</artifactId>
    </dependency>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>apache-client3</artifactId>
    </dependency>
</dependencies>
套件名稱 com.amazonaws.util software.amazon.awssdk.imds
實例化方法

使用靜態公用程式方法；無執行個體化：

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

使用靜態原廠方法：

Ec2MetadataClient client = Ec2MetadataClient.create();

或使用建置器方法：

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
用戶端類型 僅限同步的公用程式方法： EC2MetadataUtils

同步： Ec2MetadataClient

非同步： Ec2MetadataAsyncClient

1 最新版本。 2 最新版本。

3通知 v2 apache-client模組的宣告。EC2 中繼資料公用程式的 V2 需要實作同步中繼資料用戶端的 SdkHttpClient 界面，或非同步中繼資料用戶端的 SdkAsyncHttpClient界面。 EC2 在 中設定 HTTP 用戶端 AWS SDK for Java 2.x 區段顯示您可以使用的 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();

請參閱執行個體中繼資料類別，以尋找請求中繼資料所需的路徑。

注意

當您在 v2 中使用執行個體中繼資料用戶端時，您應該目標是針對擷取中繼資料的所有請求使用相同的用戶端。

行為變更

JSON 資料

在 EC2 上，本機執行的執行個體中繼資料服務 (IMDS) 會以 JSON 格式字串傳回一些中繼資料。其中一個範例是執行個體身分文件的動態中繼資料。

v1 API 包含每個執行個體身分中繼資料的個別方法，而 v2 API 會直接傳回 JSON 字串。若要使用 JSON 字串，您可以使用文件 API 來剖析回應並導覽 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_EC2_METADATA_SERVICE_ENDPOINT 系統屬性： aws.ec2MetadataServiceEndpoint
預設值：http://169.254.169.254 Config 檔案：~.aws/config使用 ec2_metadata_service_endpoint設定
已解析與 相關聯的值 endpoint-mode
預設值：http://169.254.169.254

v2 中的端點解析

當您使用建置器明確設定端點時，該端點值會優先於所有其他設定。執行下列程式碼時，aws.ec2MetadataServiceEndpoint系統屬性和組態檔案ec2_metadata_service_endpoint設定會在存在時忽略。

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

端點模式

使用 v2，您可以指定端點模式，將中繼資料用戶端設定為使用 IPv4 或 IPv6 的預設端點值。端點模式不適用於 v1。用於 IPv4 的預設值為 IPv6 http://[fd00:ec2::254] 的 http://169.254.169.254和 。 IPv6

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

可能的值
用戶端建置器組態方法： endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
系統屬性 aws.ec2MetadataServiceEndpointMode IPv4、 IPv6（大小寫並不重要）
組態檔案： ~.aws/config ec2_metadata_service_endpoint 設定 IPv4、 IPv6（大小寫並不重要）
先前未指定 使用 IPv4

開發套件在 v2 endpoint-mode中如何解析 endpoint或

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

  2. 如果您未在程式碼中設定值，則 SDK 會先尋找外部組態，接著尋找組態檔案中的設定。

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

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

  3. 最後，如果軟體開發套件找不到外部設定，而且您尚未在程式碼中設定中繼資料用戶端，則軟體開發套件會使用 的 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_METADATA_SERVICE_TIMEOUT環境變數設定連線逾時。預設值為 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();