Use o AWS SDK for Java 2.x

Depois de concluir as etapas em Configuração do SDK, você estará pronto para fazer solicitações a AWS serviços como Amazon S3, DynamoDB, IAM, Amazon EC2 e muito mais.

Trabalhar com os clientes de serviço

Crie um cliente de serviço

Para fazer uma solicitação a um AWS service (Serviço da AWS), você deve primeiro instanciar um cliente de serviço para esse serviço usando o método estático de fábrica,. builder() O método builder() retorna um objeto builder que permite personalizar o cliente de serviço. Os métodos setter fluentes retornam o objeto builder, de maneira que você possa vincular as chamadas ao método por conveniência e obter um código mais legível. Após configurar as propriedades desejadas, você poderá chamar o método build() para criar o cliente.

Como exemplo, o trecho de código a seguir instancia um objeto Ec2Client como um cliente de serviço para o Amazon EC2.

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

nota

Os clientes de serviço no SDK devem ser livres de thread. Para obter uma melhor performance, trate-os como objetos de longa duração. Cada cliente tem o próprio recurso do grupo de conexões, que é liberado quando o lixo do cliente é coletado.

Um objeto cliente de serviço é imutável, então você deve criar um novo cliente para cada serviço para o qual você faz solicitações ou se quiser usar uma configuração diferente para fazer solicitações para o mesmo serviço.

Não é necessário especificar o Region no Service Client Builder para todos os AWS serviços; no entanto, é uma prática recomendada definir a região para as chamadas de API que você faz em seus aplicativos. Consulte a seleção da região da AWS para obter mais informações.

Configuração padrão de cliente

Os compiladores de cliente têm outro método de fábrica chamado create(). Esse método cria um cliente de serviço com a configuração padrão. Ele usa a cadeia de provedores padrão para carregar as credenciais e a Região da AWS. Se as credenciais ou a região não puderem ser determinadas pelo ambiente no qual o aplicativo estiver em execução, a chamada a create falhará. Consulte Como usar credenciais e Seleção de região para obter mais informações sobre como o SDK determina as credenciais e a região a ser usada.

Por exemplo, o seguinte trecho de código instancia um objeto DynamoDbClient como um cliente de serviço para o Amazon DynamoDB:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Configurar a página de serviço

Para personalizar as configurações de um cliente de serviço, use os métodos de configuração no método de fábrica builder(). Por conveniência e para criar um código mais legível, encadeie os métodos para definir múltiplas opções de configuração.

O exemplo a seguir mostra um S3Client que está configurado com várias configurações personalizadas.

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

Fazer solicitações.

Use o cliente de serviço para fazer solicitações ao correspondente AWS service (Serviço da AWS).

Por exemplo, este trecho de código mostra como criar um objeto RunInstancesRequest para criar uma nova instância do 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);

Em vez de criar uma solicitação e transmitir a instância, o SDK fornece criadores que você pode usar para criar uma solicitação. Com um criador, é possível usar expressões do lambda em Java para criar a solicitação “em linha”.

O exemplo a seguir reescreve o exemplo anterior usando a versão de runInstances método que usa um criador para criar a solicitação.

// Create the request by using a lambda expression.
RunInstancesResponse response = ec2.runInstances(r -> r
                .imageId(amiId)
                .instanceType(InstanceType.T1_MICRO)
                .maxCount(1)
                .minCount(1));

Manipulador de resposta

O SDK retorna um objeto de resposta para a maioria das operações de serviço. Seu código pode processar as informações no objeto de resposta de acordo com suas necessidades.

Por exemplo, o trecho de código a seguir imprime o ID da primeira instância retornado com o RunInstancesResponseobjeto da solicitação anterior.

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

No entanto, nem todas as operações retornam um objeto de resposta com dados específicos do serviço. Nessas situações, você pode consultar o status da resposta HTTP para saber se a operação foi bem-sucedida.

Por exemplo, o código no trecho a seguir verifica a resposta HTTP para ver se a DeleteContactListoperação do Amazon Simple Email Service foi bem-sucedida.

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

Feche o cliente de serviço

Como prática recomendada, você deve usar um cliente de serviço para múltiplas chamadas de serviço de API durante a vida de um aplicativo. No entanto, se você precisar de um cliente de serviço para uso único ou não precisar mais do cliente de serviço, feche-o.

Chame o método close() quando o cliente de serviço não for mais necessário para liberar recursos.

ec2Client.close();

Se precisar de um cliente de serviço para uso único, você pode instanciar o cliente de serviço como um recurso em uma declaração try-com recursos. Os clientes de serviço implementam a interface Autoclosable, então o JDK chama automaticamente o método close() no fim da instrução.

O exemplo a seguir demonstra como usar um cliente de serviço para uma chamada única. O StsClient que chama o AWS Security Token Service é fechado após retornar o ID da conta.

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

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

Tratamento de exceções

O SDK usa exceções de tempo de execução (ou não verificadas), fornecendo controle detalhado sobre o tratamento de erros e garantindo que o tratamento de exceções seja escalonado com seu aplicativo.

Uma SdkServiceException, ou uma de suas subclasses, é a forma mais comum de exceção que o SDK lançará. Essas exceções representam respostas do serviço da AWS . Você também pode lidar com uma SdkClientException, que ocorre quando há um problema no lado do cliente (ou seja, em seu ambiente de desenvolvimento ou do aplicativo), como uma falha na conexão de rede.

Esse trecho de código demonstra uma maneira de lidar com exceções de serviço ao fazer upload de um arquivo para o Amazon S3. O código de exemplo envolve as exceções de cliente e de servidor, registra os detalhes e sai do aplicativo.

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

Para obter mais informações, consulte Tratamento de exceções.

Como usar waiters

Algumas solicitações demoram para serem processadas, como criar uma nova tabela DynamoDB ou criar um novo Amazon S3 bucket. Para garantir que o recurso esteja pronto antes que seu código continue sendo executado, use um Waiter.

Por exemplo, esse trecho de código cria uma nova tabela (“MyTable”) em DynamoDB, espera que a tabela esteja em um ACTIVE status e, em seguida, imprime a resposta:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();
DynamoDbWaiter dynamoDbWaiter = dynamoDbClient.waiter();

WaiterResponse<DescribeTableResponse> waiterResponse =
   dynamoDbWaiter.waitUntilTableExists(r -> r.tableName("myTable"));

waiterResponse.matched().response().ifPresent(System.out::println);

Para obter mais informações, consulte Como usar waiters.

Clientes HTTP

Você pode alterar a configuração padrão dos clientes de HTTP em aplicativos que você cria com o AWS SDK for Java. Para obter informações sobre como definir clientes e configurações HTTP, consulte Configurações HTTP.

Tempos limite

Você pode configurar tempos limite para cada um dos seus clientes de serviço usando os apiCallTimeoute os apiCallAttemptTimeoutsetters do. ClientOverrideConfiguration.Builder A configuração apiCallTimeout é o tempo para permitir que o cliente conclua a execução de uma chamada de API. A apiCallAttemptTimeout configuração é a quantidade de tempo de espera até que cada solicitação HTTP (nova tentativa) seja concluída antes de desistir.

O exemplo a seguir define os dois tempos limite para um cliente S3.

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L))).
    build();

Você também pode definir tempos limite no nível da solicitação configurando um AwsRequestOverrideConfiguratione fornecendo-o ao objeto de solicitação com o overrideConfiguration método.

O exemplo a seguir usa as mesmas configurações de tempo limite, mas no nível da solicitação para uma operação do S3PutObject.

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

Interceptores de execução

Você pode escrever um código que intercepte a execução das solicitações e respostas de API em diferentes partes do ciclo de vida delas. Isso permite que você publique métricas, modifique uma solicitação em andamento, depure o processamento da solicitação, visualize exceções e muito mais. Para obter mais informações, consulte a ExecutionInterceptor interface na Referência AWS SDK for Java da API.

Mais informações

• Para obter exemplos completos dos trechos de código acima, consulte Trabalhando com Amazon DynamoDB, Trabalhando com Amazon EC2 e Trabalhando com. Amazon S3