Realización de solicitudes de Servicio de AWS con AWS SDK for Java 2.x

Uso de clientes de servicio para realizar solicitudes

Tras completar los pasos de Configuración del SDK y aprender a configurar clientes de servicio, está listo para efectuar solicitudes a servicios de AWS como Amazon S3, Amazon DynamoDB, AWS Identity and Access Management, Amazon EC2, etc.

Crear un cliente de servicio

Para hacer una solicitud a un Servicio de AWS, primero debe crear una instancia de un cliente para ese servicio según el método de fábrica estático 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();

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 predeterminados para cargar credenciales y la cadena de proveedores predeterminados de 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 obtener información detallada sobre cómo configurar clientes de servicio, consulte Configuración externa de clientes y Configuración de clientes en código.

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 identificador de la cuenta.

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

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

Hacer solicitudes

Utilice el cliente de servicio para hacer 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 pasar la instancia, el SDK proporciona una API fluida que puede usar para crear una solicitud. Con la API fluida, 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));

Utilice solicitudes para anular la configuración del cliente

Aunque un cliente de servicio es inmutable, puede anular muchos de sus ajustes en el nivel de solicitud. Al crear una solicitud, puede proporcionar una instancia de AWSRequestOverrideConfiguration para proporcionar la configuración anulada. Algunos de los métodos que puede utilizar para anular la configuración del cliente son:

Para ver un ejemplo de cómo anular la configuración de un cliente con una solicitud, suponga que tiene el siguiente cliente de S3 que usa la configuración predeterminada.

S3Client s3Client = S3Client.create();

Desea descargar un archivo grande y asegurarse de que no se agote el tiempo de espera de la solicitud antes de que finalice la descarga. Para ello, aumente los valores de tiempo de espera de una sola solicitud de GetObject, como se muestra en el código siguiente.

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

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 en función de sus necesidades.

Por ejemplo, el siguiente fragmento de código imprime el primer identificador de instancia devuelto con el objeto RunInstancesResponse 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 ver si la operación DeleteContactList 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());
}