使用服务客户端处理异常使用 waiter HTTP 客户端超时执行拦截器其他信息

使用 AWS SDK for Java 2.x

完成设置软件开发工具包中的步骤后，您就可以向诸如 Amazon S3、D ynamoDB、IAM、Amazon EC2 等 AWS 服务提出请求了。

使用服务客户端

创建服务客户端

要向发出请求 AWS 服务，必须先使用静态工厂方法为该服务实例化服务客户端。builder()该 builder() 方法返回一个允许您自定义服务客户端的 builder 对象。常用的 setter 方法会返回 builder 对象，由此可以将方法调用组合起来，这样不仅方便而且代码更加便于阅读。在配置了所需属性后，可以调用 build() 方法创建客户端。

例如，以下代码段将 Ec2Client 对象实例化为 Amazon EC2 的服务客户端。


Region region = Region.US_WEST_2;
Ec2Client ec2Client = Ec2Client.builder()
        .region(region)
        .build();

注意

开发工具包中的服务客户端是线程安全的。为了获得最佳性能，应将其作为永久对象。每个客户端自己有连接池资源，当客户端收集到垃圾时相应资源会释放。

服务客户端对象是不可变的，因此您必须为向其发出请求的每个服务创建一个新的客户端，或者，如果您希望使用不同的配置向同一服务发出请求，也需要创建一个新的客户端。

并非所有 AWS 服务都需要Region在服务客户端生成器中指定；但是，最佳做法是为在应用程序中进行的 API 调用设置区域。有关更多信息，请参阅 AWS 区域选择。

默认客户端配置

客户端生成器包含名为 create() 的另一个工厂方法。此方法将使用默认配置创建服务客户端。该客户端使用默认提供程序链加载凭证和 AWS 区域区域。如果不能根据运行应用程序的环境确定凭证或区域，则对 create 的调用失败。有关 SDK 如何确定要使用的凭证和区域的更多信息，请参阅使用凭证和区域选择。

例如，以下代码段将 DynamoDbClient 对象实例化为 Amazon DynamoDB 的服务客户端。


DynamoDbClient dynamoDbClient = DynamoDbClient.create();

配置服务客户端

要自定义服务客户端的配置，请使用 builder() 工厂方法上的 setter。为了方便起见并创建更具可读性的代码，请将方法链接起来以设置多个配置选项。

以下示例显示了配置了多个自定义设置的 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() 方法。

以下示例演示如何使用服务客户端进行一次性调用。调用StsClient AWS Security Token Service 的，将在返回账户 ID 后关闭。


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

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

处理异常

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

有关更多信息，请参阅处理异常。

使用 waiter

有些请求需要时间才能处理，例如在中创建新表 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);

有关更多信息，请参阅使用 waiter。

HTTP 客户端

在使用 AWS SDK for Java构建的应用程序中，您可以更改 HTTP 客户端的默认配置。有关如何配置 HTTP 客户端和设置的信息，请参阅 HTTP 配置。

超时

您可以使用apiCallTimeout和的apiCallAttemptTimeout设置器为每个服务客户端配置超时。ClientOverrideConfiguration.BuilderapiCallTimeout 设置是允许客户端完成 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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

设置 GraalVM 原生映像项目

向 SDK 提供临时凭证