Fazer solicitações de AWS service (Serviço da AWS) usando o AWS SDK for Java 2.x

Usar clientes de serviço para fazer solicitações

Após concluir as etapas em Configurar o SDK e entender como configurar clientes de serviço, você poderá fazer solicitações aos serviços da AWS como o Amazon S3, o Amazon DynamoDB, o AWS Identity and Access Management, o Amazon EC2 e muito mais.

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

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 cadeia de provedores da Região da AWS padrão. 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 clientes de serviço

Consulte detalhes sobre como configurar clientes de serviço em Configuração externa do cliente e Configuração do cliente no código.

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

Fazer solicitações.

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

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 uma API fluente que você pode usar para criar uma solicitação. Com a API fluente, é 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));

Usar solicitações para substituir a configuração do cliente

Embora um cliente de serviço seja imutável, é possível substituir muitas de suas configurações no nível da solicitação. Ao criar uma solicitação, você pode fornecer uma instância AwsRequestOverrideConfiguration para fornecer as configurações substituídas. Alguns dos métodos que você pode usar para substituir as configurações do cliente são:

Para obter um exemplo de substituição de uma configuração de cliente por uma solicitação, suponha que você tenha o seguinte cliente do S3 que usa configurações padrão.

S3Client s3Client = S3Client.create();

Você deseja baixar um arquivo grande e garantir que a solicitação não atinja o tempo limite antes que o download termine. Para fazer isso, aumente os valores de tempo limite para apenas uma única solicitação GetObject, conforme mostrado no código a seguir.

Standard API

AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(100L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

GetObjectRequest request = GetObjectRequest.builder()
    .bucket("amzn-s3-demo-bucket")
    .key("demo-key")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

Fluent API

s3Client.getObject(b -> b
        .bucket("amzn-s3-demo-bucket")
        .key("demo-key")
        .overrideConfiguration(c -> c
            .apiCallTimeout(Duration.ofSeconds(100L))
            .apiCallAttemptTimeout(Duration.ofSeconds(25L))),
    myPath);

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 da 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 objeto RunInstancesResponse 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 operação DeleteContactList 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());
}