使用 AWS SDK for Java 2.x

完成設定開發套件中的步驟後，您就可以準備好對 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();

注意

開發套件中的服務用戶端是安全執行緒。為求最佳效能，請將它們視為長期執行的物件。每個用戶端都有自己的連線集區資源，在用戶端回收記憶體時釋出。

服務客戶端對象是不可變的，因此您必須為向其發出請求的每個服務創建一個新的客戶端，或者如果您想要使用不同的配置向同一服務發出請求。

並非所有服務都需要Region在服 AWS 務用戶端產生器中指定；不過，最佳做法是為您在應用程式中進行的 API 呼叫設定區域。如需詳細資訊，請參閱AWS 區域選取。

預設用戶端組態

用戶端建置器有另一個原廠方法，名為 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();

提出要求

使用服務客戶端向相應的請求 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 不會建立要求並傳入執行個體，而是提供可用來建立要求的建置工具。使用構建器，您可以使用 Java lambda 表達式來創建「在線」請求。

下列範例會使用建置器建立要求的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));

處理回應

SDK 會傳回大部分服務作業的回應物件。您的代碼可以根據您的需要處理響應對象中的信息。

例如，下面的代碼片段打印出與先前請求的RunInstancesResponse對象返回的第一個實例 ID。


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

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

例如，下列程式碼片段中的程式碼會檢查 HTTP 回應，以查看 Amazon 簡易電子郵件服務的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());
}

關閉服務用戶端

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

當不再需要服務客戶端以釋放資源時調用該close()方法。


ec2Client.close();

如果您需要一次性使用的服務客戶端，則可以將服務客戶端實例化為 try-with-resources 語句中的資源。服務客戶端實現Autoclosable接口，因此 JDK 會在語句末尾自動調用該close()方法。

下列範例會示範如何使用服務用戶端進行一次性呼叫。在傳回帳戶 ID 之後StsClient，呼叫的會關閉。 AWS Security Token Service


import software.amazon.awssdk.services.sts.StsClient;

String getAccountID() {
    try (StsClient stsClient = StsClient.create()) {
       return stsClient.getCallerIdentity().account();
    }
}

處理異常

SDK 會使用執行階段 (或未核取) 例外狀況，提供您對錯誤處理的精細控制，並確保例外狀況處理能隨應用程式擴充。

或它的子類之一，是 SDK 將拋出的最常見的異常形式。SdkServiceException這些例外狀況代表 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);

如需詳細資訊，請參閱使用服務員。

HTTP 用戶端

您可以在使用建置的應用程式中變更 HTTP 用戶端的預設組態 AWS SDK for Java。如需如何設定 HTTP 用戶端和設定的詳細資訊，請參閱 HTTP 組態。

重試

您可以變更服務用戶端中重試的預設設定，包括重試模式和退回策略。如需詳細資訊，請參閱 AWS SDK for Java API 參考中的RetryPolicy類別。

如需有關 AWS 服務中重試的詳細資訊，請參閱. AWS

逾時

您可以使用的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 no 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 API 參考中的ExecutionInterceptor介面。

其他資訊

如需上述程式碼片段的完整範例 Amazon DynamoDB，請參閱使用 Amazon EC2 、使用和使用 Amazon S3。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

設定 GraalVM 原生映像檔專案

為 SDK 提供臨時憑證