使用 Amazon SDK for Java 2.x - Amazon SDK for Java 2.x
使用服务客户端处理异常使用 waiterHTTP 客户端重试超时执行拦截器其他信息
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 Amazon SDK for Java 2.x

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

使用服务客户端

创建服务客户端

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

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

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

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

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

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

默认客户端配置

客户端生成器包含名为 create() 的另一个工厂方法。此方法将使用默认配置创建服务客户端。该客户端使用默认提供程序链加载凭证和 Amazon Web Services 区域区域。如果不能根据运行应用程序的环境确定凭证或区域，则对 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();

提出请求

使用服务客户端向对应的发出请求 Amazon Web Service。

例如，以下代码段演示如何创建 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));

处理响应

您可以使用响应处理程序来处理 Amazon Web Service发回的响应。

例如，以下代码段演示如何创建 RunInstancesResponse 对象，以处理来自 Amazon EC2 的响应，该代码段将打印为上述示例请求创建的新实例的 instanceId：

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

关闭服务客户端

作为最佳实践，您应该在应用程序的生命周期内使用服务客户端进行多个 API 服务调用。但是，如果您需要一次性使用服务客户端，或者不再需要该服务客户端，请将其关闭。

当不再需要服务客户端时，请调用 close() 方法，以释放资源。

ec2Client.close();

如果您需要一次性使用服务客户端，则可以通过 try-with-resources 语句将服务客户端实例化为资源。服务客户端将实现 Autoclosable 接口，因此 JDK 会在语句末尾自动调用 close() 方法。

以下示例演示如何使用服务客户端进行一次性调用。调用StsClient Amazon 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 会引发的最常见异常形式。这些异常表示来自 Amazon 服务的响应。您还可以处理在客户端（即开发或应用程序环境中）出现问题（例如网络连接故障）时发生的 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 客户端

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

重试

您可以更改服务客户端中的默认重试设置，包括重试模式和回退策略。有关更多信息，请参阅 Amazon SDK for Java API 参考中的RetryPolicy类。

有关 Amazon 服务重试的更多信息，请参阅中的错误重试和指数退缩。 Amazon

超时

您可以使用 apiCallTimeout 和 apiCallAttemptTimeout setter 为每个服务客户端配置超时。apiCallTimeout 设置是允许客户端完成 API 调用的执行所需的时间。apiCallAttemptTimeout 设置是在放弃之前等待 HTTP 请求完成的时间。

有关更多信息，请参阅 Amazon SDK for Java API 参考apiCallAttemptTimeout中的apiCallTimeout和。

执行拦截器

您可以编写代码，在请求/响应生命周期的不同阶段拦截 API 请求和响应的执行。这使您能够发布指标、修改正在进行的请求、调试请求处理、查看异常等。有关更多信息，请参阅 Amazon SDK for Java API 参考中的ExecutionInterceptor接口。

其他信息