本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon EC2 執行個體中繼資料
Amazon EC2 執行個體中繼資料服務的 Java SDK 用戶端 （中繼資料用戶端） 可讓您的應用程式存取其本機 EC2 執行個體上的中繼資料。中繼資料用戶端使用 [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) (Instance Metadata Service v2) 的本機執行個體，並使用工作階段導向請求。
開發套件提供兩種用戶端類別。同步`[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 成品新增至您的專案。您也需要 classpath 上 `[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 中央儲存庫](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
```
## 使用中繼資料用戶端
### 執行個體化中繼資料用戶端
當 classpath 上只有一個`SdkHttpClient`介面實作`Ec2MetadataClient`時，您可以執行個體化同步的執行個體。若要這麼做，請呼叫靜態`Ec2MetadataClient#create()`方法，如下列程式碼片段所示。
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
如果您的應用程式有多個 `SdkHttpClient`或 `SdkHttpAsyncClient` 介面實作，您必須指定中繼資料用戶端要使用的實作，如 [可設定的 HTTP 用戶端](#examples-ec2-IMDS-features-http)一節所示。
**注意**
對於大多數服務用戶端，例如 Amazon S3，適用於 Java 的 SDK 會自動新增 `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) 來更詳細地檢查回應。請參閱執行個體[中繼資料類別圖表](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html)，以了解哪些中繼資料類別提供 JSON 格式的回應。
## 設定中繼資料用戶端
### 重試
您可以使用重試機制設定中繼資料用戶端。如果您這麼做，則用戶端可以自動重試因意外原因失敗的請求。根據預設，用戶端會在失敗的請求上重試三次，並在嘗試之間有指數退避時間。
如果您的使用案例需要不同的重試機制，您可以在其建置器上使用 `retryPolicy`方法自訂用戶端。例如，下列範例顯示同步用戶端，其設定在嘗試與五次重試嘗試之間的固定延遲為兩秒。
```
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 版本
根據預設，中繼資料用戶端會使用位於 的 IPV4 端點`http://169.254.169.254`。若要將用戶端變更為使用 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 用戶端
每個中繼資料用戶端的建置器都有一種`httpClient`方法，您可以用來提供自訂的 HTTP 用戶端。
下列範例顯示自訂`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)主題提供如何設定適用於 Java 的 開發套件中可用 HTTP 用戶端的詳細資訊。
### 權杖快取
由於中繼資料用戶端使用 IMDSv2，所有請求都會與工作階段相關聯。工作階段是由具有過期的字符定義，中繼資料用戶端會為您管理。每個中繼資料請求都會自動重複使用字符，直到過期為止。
根據預設，字符會持續六個小時 (21，600 秒）。建議您保留預設time-to-live值，除非您的特定使用案例需要進階組態。
如有需要，請使用`tokenTtl`建置器方法來設定持續時間。例如，以下程式碼片段中的程式碼會建立工作階段持續時間為五分鐘的用戶端。
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.tokenTtl(Duration.ofMinutes(5))
.build();
```
如果您省略在建置器上呼叫 `tokenTtl`方法，則會改用預設持續時間 21，600。