使用 Amazon SDK for Java 2.x

完成设置中的步骤后SDK，您就可以向诸如 Amazon S3、DynamoD IAM B、Amazon EC2 等 Amazon 服务提出请求了。

使用服务客户端

创建服务客户端

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

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


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

注意

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

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

并非所有 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();

关闭服务客户端

作为最佳实践，您应该在应用程序的生命周期内使用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();
    }
}

提出请求

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

例如，以下代码段展示了如何创建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的方法供您创建请求。使用 fluent，API你可以使用 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));

使用请求来覆盖客户端配置

尽管服务客户端是不可变的，但你可以在请求级别覆盖它的许多设置。在构建请求时，您可以提供一个AwsRequestOverrideConfiguration实例来提供被覆盖的设置。可以用来覆盖客户端设置的一些方法有：

apiCallAttemptTimeout
apiCallTimeout
credentialProvider
compressionConfiguration
putHeader

有关使用请求覆盖客户端设置的示例，假设您有以下 S3 客户端使用默认设置。


S3Client s3Client = S3Client.create();

你想下载一个大文件，并要确保在下载完成之前请求不会超时。为此，请仅增加单个GetObject请求的超时值，如以下代码所示。

处理响应

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

处理异常

SDK使用运行时（或未选中）异常，为您提供对错误处理的精细控制，并确保异常处理会随着您的应用程序而扩展。

A 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。

设置超时

您可以使用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请求和响应的执行情况。这使您能够发布指标、修改正在进行的请求、调试请求处理、查看异常等。有关更多信息，请参阅《 Amazon SDK for Java API参考》中的ExecutionInterceptor接口。

Javascript 在您的浏览器中被禁用或不可用。

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

设置 GraalVM 原生映像项目

配置SDK身份验证