Usa el AWS SDK for Java 2.x

Tras completar los pasos de Configuración del SDK, estará listo para realizar solicitudes a AWS servicios como Amazon S3, DynamoDB, IAM, Amazon EC2 y más.

Trabajar con los clientes de servicios

Crear un cliente de servicio

Para realizar una solicitud a un Servicio de AWS, primero debe crear una instancia de un cliente de servicio para ese servicio mediante el método estático de fábrica,. builder() El método builder() devuelve un objeto builder que permite personalizar el cliente de servicio. Los métodos setter Fluent devuelven el objeto builder para que pueda encadenar fácilmente las llamadas a los métodos y para simplificar la lectura del código. Después de configurar las propiedades que desee, puede llamar al método build() para crear el cliente.

A modo de ejemplo, el siguiente fragmento de código crea una instancia de un objeto Ec2Client como cliente de servicio para Amazon EC2.

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

nota

Los clientes de servicios del SDK son seguros para subprocesos. Para obtener el máximo desempeño, trátelos como objetos de larga duración. Cada cliente tiene su propio recurso de grupo de conexiones que se libera cuando el cliente recopila los elementos no utilizados.

Un objeto cliente de servicio es inmutable, por lo que deberá crear un nuevo cliente para cada servicio al que haga peticiones, o si desea utilizar una configuración diferente para realizar peticiones al mismo servicio.

No es necesario especificarlo Region en el generador de clientes de AWS servicios para todos los servicios; sin embargo, se recomienda establecer la región de las llamadas a la API que realice en sus aplicaciones. Para obtener más información, consulte la Selección de regiones de AWS.

Configuración predeterminada de cliente

Los creadores de clientes tienen otro método de fábrica denominado create(). Este método crea un servicio cliente con la configuración predeterminada. Utiliza la cadena de proveedores predeterminada para cargar las credenciales y la Región de AWS. Si las credenciales o la región no se pueden determinar a partir del entorno en el que se ejecuta la aplicación, la llamada a create produce un error. Consulte Uso de credenciales y Selección de regiones para obtener más información acerca de cómo el SDK determinan las credenciales y la región.

A modo de ejemplo, el siguiente fragmento de código crea una instancia de un objeto DynamoDbClient como cliente de servicio para Amazon DynamoDB:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Configurar clientes de servicio

Para personalizar la configuración de un cliente de servicio, utilice los parámetros del método de fábrica builder(). Para mayor comodidad y para crear un código más legible, encadene los métodos para establecer varias opciones de configuración.

El siguiente ejemplo muestra un S3Client configurado con varios ajustes personalizados.

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

Hacer solicitudes

Utilice el cliente de servicio para realizar solicitudes al correspondiente Servicio de AWS.

Por ejemplo, este fragmento de código muestra cómo crear un objeto de RunInstancesRequest para crear una nueva instancia de 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);

En lugar de crear una solicitud y pasarla a la instancia, el SDK proporciona creadores que puede usar para crear una solicitud. Con un creador, puede usar expresiones lambda de Java para crear la solicitud “en línea”.

En el siguiente ejemplo, se reescribe el ejemplo anterior mediante la versión del runInstances método que utiliza un creador para crear la solicitud.

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

Tratamiento de respuestas

El SDK devuelve un objeto de respuesta para la mayoría de las operaciones de servicio. El código puede procesar la información del objeto de respuesta según sus necesidades.

Por ejemplo, el siguiente fragmento de código imprime el identificador de la primera instancia devuelto con el RunInstancesResponseobjeto en la solicitud anterior.

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

Sin embargo, no todas las operaciones devuelven un objeto de respuesta con datos específicos del servicio. En estas situaciones, puede consultar el estado de la respuesta HTTP para saber si la operación se realizó correctamente.

Por ejemplo, el código del siguiente fragmento comprueba la respuesta HTTP para comprobar si la DeleteContactListoperación de Amazon Simple Email Service se ha realizado correctamente.

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

Cerrar el cliente de servicio

Como práctica recomendada, debe utilizar un cliente de servicio para varias llamadas al servicio de la API durante la vida útil de una aplicación. Sin embargo, si necesita un cliente de servicio para un solo uso o ya no lo necesita, ciérrelo.

Para liberar recursos, llame al método close() cuando el cliente de servicio deje de ser necesario.

ec2Client.close();

Si necesita un cliente de servicio para un solo uso, puede crear una instancia del cliente de servicio como un recurso en una instrucción try-with-resources. Los clientes de servicio implementan la interfaz de Autoclosable, por lo que el JDK llama automáticamente al método close() al final de la instrucción.

En el ejemplo siguiente, se muestra cómo utilizar un cliente de servicio para una llamada única. El StsClient que llama al AWS Security Token Service se cierra después de devolver el ID de la cuenta.

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

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

Tratamiento de excepciones

El SDK utiliza excepciones en tiempo de ejecución (o no comprobadas), lo que te proporciona un control pormenorizado sobre el tratamiento de errores y garantiza que el tratamiento de excepciones se adapte a su aplicación.

Una SdkServiceException, o una de sus subclases, es la forma de excepción más común que generará el SDK. Estas excepciones representan las respuestas del servicio de AWS . También puede tratar una SdkClientException, que se produce cuando hay un problema en el cliente (es decir, en el entorno de desarrollo o de aplicaciones), como un fallo de conexión de red.

Este fragmento de código muestra una forma de gestionar las excepciones de servicio al cargar un archivo en Amazon S3. El código de ejemplo captura las excepciones del cliente y del servidor, registra los detalles y sale de la aplicación.

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

Consulte Tratamiento de excepciones para obtener más información.

Utilizar esperadores

El procesamiento de algunas solicitudes lleva tiempo, como la creación de una nueva tabla DynamoDB o la creación de un nuevo Amazon S3 depósito. Para asegurarse de que el recurso esté listo antes de que el código siga ejecutándose, use un esperador.

Por ejemplo, este fragmento de código crea una tabla nueva («MyTable») en DynamoDB, espera a que la tabla tenga un ACTIVE estado y, a continuación, imprime la respuesta:

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

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

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

Consulte Uso de los esperadores para obtener más información.

Clientes de HTTP

Puede cambiar la configuración predeterminada de los clientes HTTP en las aplicaciones que compile con el AWS SDK for Java. Para obtener información sobre cómo configurar los clientes y las opciones HTTP, consulte Configuración HTTP.

Tiempos de espera

Puede configurar los tiempos de espera para cada uno de sus clientes de servicio mediante los valores apiCallTimeouty los valores de. apiCallAttemptTimeoutClientOverrideConfiguration.Builder La configuración apiCallTimeout es la cantidad de tiempo que se tarda en permitir que el cliente complete la ejecución de una llamada a la API. La apiCallAttemptTimeout configuración es el tiempo que se debe esperar a que se complete cada solicitud HTTP (reintento) antes de darse por vencida.

El siguiente ejemplo establece ambos tiempos de espera para un cliente S3.

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

También puede establecer los tiempos de espera en el nivel de solicitud configurando un AwsRequestOverrideConfigurationy proporcionándolo al objeto de solicitud con el overrideConfiguration método.

En el siguiente ejemplo, se utiliza la misma configuración de tiempo de espera, pero en el nivel de solicitud para una operación de 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 ejecución

Puede escribir código que intercepte la ejecución de las solicitudes y respuestas de la API en distintas partes del ciclo de vida de la solicitud/respuesta. Esto permite publicar métricas, modificar una solicitud durante el proceso, depurar el procesamiento de las solicitudes, ver las excepciones y mucho más. Para obtener más información, consulte la ExecutionInterceptor interfaz en la referencia de la AWS SDK for Java API.

Información adicional

• Para ver ejemplos completos de los fragmentos de código anteriores, consulte Trabajar con Amazon DynamoDB, Trabajar con Amazon EC2 y Trabajar con. Amazon S3