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

使用 AWS SDK for Java 2.x

完成設定 SDK中的步驟後，您就可以向 Amazon S3、DynamoDBIAM、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決定要使用之憑證和區域的詳細資訊。

例如，下列程式碼程式碼片段會將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);

SDK 提供流暢API的 來建立請求，而不是建立請求並在執行個體中傳遞。透過流暢，API您可以使用 Java lambda 表達式來建立請求 'in-line'。

下列範例會使用runInstances使用建置器建立請求的方法版本來重寫先前的範例。

// 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請求的逾時值，如下列程式碼所示。

Standard API

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

Fluent API

s3Client.getObject(b -> b
        .bucket("DOC-EXAMPLE-BUCKET")
        .key("DOC-EXAMPLE-KEY")
        .overrideConfiguration(c -> c
            .apiCallTimeout(Duration.ofSeconds(100L))
            .apiCallAttemptTimeout(Duration.ofSeconds(25L))),
    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 儲存貯體。若要確保資源在程式碼繼續執行之前已準備就緒，請使用 Waiter 。

例如，此程式碼片段會在 中建立新的資料表 （"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();

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

下列範例使用相同的逾時設定，但在 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請求/回應生命週期的不同部分攔截請求和回應的執行。這可讓您發佈指標、修改處理中的請求、偵錯請求處理、檢視例外狀況等。如需詳細資訊，請參閱 參考中的 AWS SDK for Java APIExecutionInterceptor介面。