Realizar Servicio de AWS solicitudes mediante el AWS SDK for Java 2.x

Uso de clientes de servicio para realizar solicitudes

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

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 Ec2Client objeto 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 servicios para todos los AWS 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 cadena Región de AWS de proveedores predeterminada. 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 los clientes de servicio, consulte Configuración del cliente externamente yConfiguración del cliente 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 ID 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 del servicio para realizar solicitudes al correspondiente Servicio de AWS.

Por ejemplo, este fragmento de código muestra cómo crear un RunInstancesRequest objeto 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 una API fluida que puedes usar para crear una solicitud. Con la API fluida, puedes 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 las 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 AwsRequestOverrideConfigurationinstancia para proporcionar la configuración anulada. Algunos de los métodos que puedes usar para anular la configuración del cliente son:

• apiCallAttemptTimeout

• apiCallTimeout

• credentialProvider

• compressionConfiguration

• putHeader

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 GetObject solicitud, tal y 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("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);

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