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 e entender como configurar clientes de serviço, você estará pronto para fazer solicitações para AWS serviços como Amazon S3, Amazon DynamoDB, AWS Identity and Access Management Amazon e muito mais. EC2
Trabalhe com clientes de serviços no AWS SDK for Java 2.x
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();
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 cadeia de Região da AWS provedores 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 a página de serviço
Para obter detalhes sobre como configurar clientes de serviço, consulte Configuração externa do cliente Configuração do cliente no código e.
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 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 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 passar na instância, o SDK fornece uma API fluente que você pode usar para criar uma solicitação. Com a API fluente, você pode usar expressões 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
// 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 AwsRequestOverrideConfiguration
-
apiCallAttemptTimeout
-
apiCallTimeout
-
credentialProvider
-
compressionConfiguration
-
putHeader
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.
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 RunInstancesResponse
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 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()); }
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
SdkClientException
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.