使用 AWS SDK for Java 2.x

完成設定 SDK 中的步驟後，您就可以向 Amazon S3、DynamoDB、IAM、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();

預設用戶端組態

用戶端建置器有另一個原廠方法，名為 create()。這個方法會使用預設組態來建立服務用戶端。它使用預設提供者鏈來載入登入資料和 AWS 區域。如果無法從應用程式執行的環境判斷登入資料或區域，呼叫 會create失敗。如需 SDK 如何決定要使用的登入資料和區域的詳細資訊，請參閱使用登入資料和區域選擇。 使用 AWS 區域

例如，下列程式碼片段會將DynamoDbClient物件執行個體化為 Amazon DynamoDB 的服務用戶端：

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

設定服務用戶端

若要自訂服務用戶端的組態，請使用builder()原廠方法的設定器。為了方便起見並建立更易讀的程式碼，請鏈結方法以設定多個組態選項。

下列範例顯示已S3Client設定數個自訂設定的 。

ClientOverrideConfiguration clientOverrideConfiguration =
    ClientOverrideConfiguration.builder()
                    .apiCallAttemptTimeout(Duration.ofSeconds(1))
                    .retryPolicy(RetryPolicy.builder().numRetries(10).build())
                    .addMetricPublisher(CloudWatchMetricPublisher.create())
                    .build();

Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
                    .region(region)
                    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
                    .overrideConfiguration(clientOverrideConfiguration)
                    .httpClientBuilder(ApacheHttpClient.builder()
                        .proxyConfiguration(proxyConfig.build(ProxyConfiguration.builder()))
                        .build())
                    .build();

關閉服務用戶端

根據最佳實務，您應該在應用程式生命週期內使用服務用戶端進行多個 API 服務呼叫。不過，如果您需要服務用戶端進行一次性使用或不再需要服務用戶端，請將其關閉。

當服務用戶端不再需要釋放資源時，呼叫 close()方法。

ec2Client.close();

如果您需要服務用戶端供一次性使用，則可以將服務用戶端執行個體化為具有資源的 陳述try式中的資源。服務用戶端實作 Autoclosable界面，因此 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)

// 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 執行個體，以提供覆寫的設定。您可以使用某些方法來覆寫用戶端設定：

如需使用 請求覆寫用戶端設定的範例，假設您有下列使用預設設定的 S3 用戶端。

S3Client s3Client = S3Client.create();

您想要下載大型檔案，並希望確保請求在下載完成之前不會逾時。若要達成此目的，請增加僅單一GetObject請求的逾時值，如下列程式碼所示。

AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(100L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

GetObjectRequest request = GetObjectRequest.builder()
    .bucket("DOC-EXAMPLE-BUCKET")
    .key("DOC-EXAMPLE-KEY")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

處理回應

SDK 會傳回大多數服務操作的回應物件。您的程式碼可以根據您的需求處理回應物件中的資訊。

例如，下列程式碼片段會列印出與上一個請求中的RunInstancesResponse物件一起傳回的第一個執行個體 ID。

RunInstancesResponse runInstancesResponse = ec2Client.runInstances(runInstancesRequest);
System.out.println(runInstancesResponse.instances().get(0).instanceId());

不過，並非所有操作都會傳回具有服務特定資料的回應物件。在這些情況下，您可以查詢 HTTP 回應狀態，以了解操作是否成功。

例如，以下程式碼片段中的程式碼會檢查 HTTP 回應，以查看 Amazon Simple Email Service DeleteContactList的操作是否成功。

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());
}

處理例外狀況

SDK 使用執行時間 （或未勾選） 例外狀況，可讓您精細控制錯誤處理，並確保例外狀況處理會隨您的應用程式而擴展。

SdkServiceException或其中一個子類別是 SDK 將擲回的最常見例外狀況形式。這些例外狀況代表來自 AWS 服務的回應。您也可以處理 SdkClientException，當用戶端發生問題時 （即在您的開發或應用程式環境中），例如網路連線失敗時，就會發生這種情況。

此程式碼片段示範在上傳檔案到 時處理服務例外狀況的一種方式 Amazon S3。範例程式碼會同時擷取用戶端和伺服器例外狀況、記錄詳細資訊，並存在應用程式。

Region region = Region.US_WEST_2;
s3Client = S3Client.builder()
        .region(region)
        .build();

try {

    PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .build();

    s3Client.putObject(putObjectRequest, RequestBody.fromString("SDK for Java test"));

} catch (S3Exception se) {
    System.err.println("Service exception thrown.");
    System.err.println(se.awsErrorDetails().errorMessage());
} catch (SdkClientExeption ce){
   System.err.println("Client exception thrown.");
   System.err.println(ce.getMessage());
} finally {
   System.exit(1);
}

如需詳細資訊，請參閱處理例外狀況。

使用等待程式

有些請求需要一些時間來處理，例如在 中建立新資料表 DynamoDB 或建立新儲存 Amazon S3 貯體。若要確保資源在程式碼繼續執行之前已就緒，請使用等待程式。

例如，此程式碼片段會在 中建立新的資料表 ("myTable") DynamoDB，等待資料表處於 ACTIVE 狀態，然後列印出回應：

DynamoDbClient dynamoDbClient = DynamoDbClient.create();
DynamoDbWaiter dynamoDbWaiter = dynamoDbClient.waiter();

WaiterResponse<DescribeTableResponse> waiterResponse =
   dynamoDbWaiter.waitUntilTableExists(r -> r.tableName("myTable"));

waiterResponse.matched().response().ifPresent(System.out::println);

如需詳細資訊，請參閱使用等待程式。

設定逾時

您可以使用 apiCallTimeout和 apiCallAttemptTimeout的設定器，為每個服務用戶端設定逾時ClientOverrideConfiguration.Builder。apiCallTimeout 設定是允許用戶端完成 API 呼叫執行的時間量。apiCallAttemptTimeout 設定是等待每個 HTTP 請求 （重試） 完成再放棄的時間量。

下列範例會設定 S3 用戶端的兩個逾時。

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L))).
    build();

您也可以在請求層級設定逾時，方法是使用 overrideConfiguration方法設定 AwsRequestOverrideConfiguration 並將其提供給請求物件。

下列範例使用相同的逾時設定，但在 S3 PutObject操作的請求層級。

S3Client basicS3Client = S3Client.create(); // Client with default timeout settings.

AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(105L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

basicS3Client.putObject(b -> b
        .bucket("DOC-EXAMPLE-BUCKET")
        .key("DOC-EXAMPLE-KEY")
        .overrideConfiguration(overrideConfiguration),
    RequestBody.fromString("test"));

執行攔截器

您可以撰寫程式碼，在請求/回應生命週期的不同部分攔截 API 請求和回應的執行。這可讓您發佈指標、修改處理中的請求、偵錯請求處理、檢視例外狀況等。如需詳細資訊，請參閱 適用於 Java 的 AWS SDK API 參考中的 ExecutionInterceptor界面。