As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Use o AWS SDK for Java 2.x

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

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 Ec2Client objeto como um cliente de serviço para a 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 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 Uso de credenciais e Seleção de região para obter mais informações sobre como SDK determina as credenciais e a região a serem usadas.

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

Feche o cliente de serviço

Como prática recomendada, você deve usar um cliente de serviço para várias chamadas API de serviço durante a vida útil 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 Autoclosable interface, então eles chamam JDK automaticamente o close() método no final 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 correspondente AWS service (Serviço da AWS).

Por exemplo, esse trecho de código mostra como criar um RunInstancesRequest objeto para criar uma nova instância da AmazonEC2:

// 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 passar na instância, ele SDK fornece uma fluência API que você pode usar para criar uma solicitação. Com o fluent, API você pode usar expressões lambda em Java para criar a solicitação 'in-line'.

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

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

Embora um cliente de serviço seja imutável, você pode substituir muitas de suas configurações no nível da solicitação. Ao criar uma solicitação, você pode fornecer uma AwsRequestOverrideConfigurationinstância 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 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 GetObject solicitação, 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("DOC-EXAMPLE-BUCKET")
    .key("DOC-EXAMPLE-KEY")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

Fluent API

s3Client.getObject(b -> b
        .bucket("DOC-EXAMPLE-BUCKET")
        .key("DOC-EXAMPLE-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 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 HTTP resposta para saber se a operação foi bem-sucedida.

Por exemplo, o código no trecho a seguir verifica a HTTP resposta 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());
}

Tratamento de exceções

SDKEle usa exceções de tempo de execução (ou não verificadas), fornecendo a você um controle refinado sobre o tratamento de erros e garantindo que o tratamento de exceções cresça com seu aplicativo.

Uma SdkServiceException, ou uma de suas subclasses, é a forma mais comum de exceção que eles SDK lançarão. 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.

Definir 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 apiCallTimeout configuração é a quantidade de tempo para permitir que o cliente conclua a execução de uma API chamada. A apiCallAttemptTimeout configuração é a quantidade de tempo de espera até que cada HTTP solicitação (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 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"));

Interceptores de execução

Você pode escrever um código que intercepte a execução de suas API solicitações e respostas em diferentes partes do ciclo de vida da solicitação/resposta. 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 AWS SDK for Java API Referência.