本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 提出 AWS 服務 請求 AWS SDK for Java 2.x
## 使用服務用戶端提出請求
完成[設定 SDK](setup.md) 中的步驟並了解如何[設定服務用戶端](configuring-service-clients.md)後，您就可以向 Amazon S3、Amazon DynamoDB、 AWS Identity and Access Management、Amazon EC2 等 AWS 服務提出請求。
### 建立服務用戶端
若要向 提出請求 AWS 服務，您必須先使用靜態原廠方法 來執行個體化該服務的服務用戶端`builder()`。`builder()` 方法會傳回可讓您自訂服務用戶端的`builder`物件。Fluent setter 方法會傳回 `builder` 物件，讓您可以鏈結方法呼叫以提供更多便利性和更易讀的程式碼。設定所需的屬性之後，請呼叫 `build()`方法來建立用戶端。
例如，下列程式碼片段會將`Ec2Client`物件執行個體化為 Amazon EC2 的服務用戶端。
```
Region region = Region.US_WEST_2;
Ec2Client ec2Client = Ec2Client.builder()
.region(region)
.build();
```
**注意**
開發套件中的服務用戶端是安全執行緒。為求最佳效能，請將它們視為長期執行的物件。每個用戶端都有自己的連線集區資源，在用戶端回收記憶體時釋出。
服務用戶端物件不可變，因此您必須為您提出請求的每個服務建立新的用戶端，或者如果您想要使用不同的組態來對相同的服務提出請求。
並非所有 AWS 服務都需要在服務用戶端建置器`Region`中指定 ；不過，最佳實務是為您在應用程式中進行的 API 呼叫設定 區域。如需詳細資訊，請參閱[AWS 區域選擇](region-selection.md)。
### 預設用戶端組態
用戶端建置器有另一個原廠方法，名為 `create()`。這個方法會使用預設組態來建立服務用戶端。它使用[預設提供者鏈](credentials-chain.md)來載入登入資料和[預設 AWS 區域 提供者鏈](region-selection.md#automatically-determine-the-aws-region-from-the-environment)。如果無法從應用程式執行的環境判斷登入資料或區域，呼叫 會`create`失敗。如需 SDK 如何決定要使用的[登入資料](credentials.md)和[區域的詳細資訊，請參閱使用登入資料和區域選擇](region-selection.md)。
例如，下列程式碼片段會將`DynamoDbClient`物件執行個體化為 Amazon DynamoDB 的服務用戶端：
```
DynamoDbClient dynamoDbClient = DynamoDbClient.create();
```
### 設定服務用戶端
如需如何設定服務用戶端的詳細資訊，請參閱 [外部用戶端組態](configuring-service-clients-ext.md)和 [程式碼中的用戶端組態](configuring-service-clients-code.md)。
### 關閉服務用戶端
根據最佳實務，您應該在應用程式生命週期內使用服務用戶端進行多個 API 服務呼叫。不過，如果您需要服務用戶端進行一次性使用或不再需要服務用戶端，請將其關閉。
當不再需要服務用戶端來釋放資源時，請呼叫 `close()`方法。
```
ec2Client.close();
```
如果您需要服務用戶端進行一次性使用，您可以將服務用戶端執行個體化為具有資源的 陳述`try`式中的資源。服務用戶端實作 `[Autoclosable](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/AutoCloseable.html)`界面，因此 JDK 會在 陳述式結尾自動呼叫 `close()`方法。
下列範例示範如何使用服務用戶端進行一次性呼叫。呼叫 `StsClient`的 會在傳回帳戶 ID 後 AWS Security Token Service 關閉。
```
import software.amazon.awssdk.services.sts.StsClient;
String getAccountID() {
try (StsClient stsClient = StsClient.create()) {
return stsClient.getCallerIdentity().account();
}
}
```
## 提出請求
使用 服務用戶端向對應的 提出請求 AWS 服務。
例如，此程式碼片段示範如何建立`RunInstancesRequest`物件以建立新的 Amazon EC2 執行個體：
```
// Create the request by using the fluid setter methods of the request builder.
RunInstancesRequest runInstancesRequest = RunInstancesRequest.builder()
.imageId(amiId)
.instanceType(InstanceType.T1_MICRO)
.maxCount(1)
.minCount(1)
.build();
// Use the configured request with the service client.
RunInstancesResponse response = ec2Client.runInstances(runInstancesRequest);
```
開發套件提供流暢的 API，可讓您用來建立請求，而不是建立請求並在執行個體中傳遞。透過流暢的 API，您可以使用 Java lambda 表達式來建立請求「內嵌」。
下列範例會使用使用建置器建立請求的 `runInstances`方法版本，來重寫先前的範例。 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#runInstances(java.util.function.Consumer)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#runInstances(java.util.function.Consumer))
```
// Create the request by using a lambda expression.
RunInstancesResponse response = ec2.runInstances(r -> r
.imageId(amiId)
.instanceType(InstanceType.T1_MICRO)
.maxCount(1)
.minCount(1));
```
### 使用請求覆寫用戶端組態
雖然服務用戶端不可變，但您可以在請求層級覆寫其許多設定。當您建置請求時，您可以提供 [AwsRequestOverrideConfiguration](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/awscore/AwsRequestOverrideConfiguration.html) 執行個體，以提供覆寫的設定。您可以使用某些方法來覆寫用戶端設定：
+ `apiCallAttemptTimeout`
+ `apiCallTimeout`
+ `credentialProvider`
+ `compressionConfiguration`
+ `putHeader`
如需使用 請求覆寫用戶端設定的範例，假設您有下列使用預設設定的 S3 用戶端。
```
S3Client s3Client = S3Client.create();
```
您想要下載大型檔案，並希望確保請求在下載完成之前不會逾時。若要達成此目的，請增加僅單一`GetObject`請求的逾時值，如下列程式碼所示。
------
#### [ Standard API ]
```
AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofSeconds(100L))
.apiCallAttemptTimeout(Duration.ofSeconds(25L))
.build();
GetObjectRequest request = GetObjectRequest.builder()
.bucket("amzn-s3-demo-bucket")
.key("demo-key")
.overrideConfiguration(overrideConfiguration)
.build();
s3Client.getObject(request, myPath);
```
------
#### [ Fluent API ]
```
s3Client.getObject(b -> b
.bucket("amzn-s3-demo-bucket")
.key("demo-key")
.overrideConfiguration(c -> c
.apiCallTimeout(Duration.ofSeconds(100L))
.apiCallAttemptTimeout(Duration.ofSeconds(25L))),
myPath);
```
------
## 處理回應
SDK 會傳回大多數服務操作的回應物件。您的程式碼可以根據您的需求處理回應物件中的資訊。
例如，下列程式碼片段會列印出與上一個請求中的[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/RunInstancesResponse.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/RunInstancesResponse.html)物件一起傳回的第一個執行個體 ID。
```
RunInstancesResponse runInstancesResponse = ec2Client.runInstances(runInstancesRequest);
System.out.println(runInstancesResponse.instances().get(0).instanceId());
```
不過，並非所有操作都會傳回具有服務特定資料的回應物件。在這些情況下，您可以查詢 HTTP 回應狀態，以了解操作是否成功。
例如，以下程式碼片段中的程式碼會檢查 HTTP 回應，以查看 Amazon Simple Email Service [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sesv2/SesV2Client.html#deleteContactList(software.amazon.awssdk.services.sesv2.model.DeleteContactListRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sesv2/SesV2Client.html#deleteContactList(software.amazon.awssdk.services.sesv2.model.DeleteContactListRequest))的操作是否成功。
```
SesV2Client sesv2Client = SesV2Client.create();
DeleteContactListRequest request = DeleteContactListRequest.builder()
.contactListName("ExampleContactListName")
.build();
DeleteContactListResponse response = sesv2Client.deleteContactList(request);
if (response.sdkHttpResponse().isSuccessful()) {
System.out.println("Contact list deleted successfully");
} else {
System.out.println("Failed to delete contact list. Status code: " + response.sdkHttpResponse().statusCode());
}
```