Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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, DynamoDBIAM, EC2 Amazon 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 de fábrica estática,. 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();

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 sobre cómo se SDK determinan las credenciales y la región que se van a utilizar.

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

Cerrar el cliente de servicio

Como práctica recomendada, debe utilizar un cliente de servicio para varias llamadas de API servicio 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 Autoclosable interfaz, por lo que llaman JDK automáticamente al close() método 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 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);

En lugar de crear una solicitud y pasar la instancia, SDK proporciona un fluido API que puedes usar para crear una solicitud. Con el fluido, API 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

Si bien 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:

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

SDKDevuelve 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 HTTP respuesta para saber si la operación se realizó correctamente.

Por ejemplo, el código del siguiente fragmento comprueba la HTTP respuesta 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());
}

Tratamiento de excepciones

SDKUtiliza excepciones en tiempo de ejecución (o no comprobadas), lo que le proporciona un control pormenorizado sobre la gestión de errores y garantiza que la gestión de excepciones se adapte a la aplicación.

Una SdkServiceException, o una de sus subclases, es la forma de excepción más común que se generará. 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 nueva tabla (» myTable «) en DynamoDB, espera a que la tabla esté en 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.

Establece tiempos de espera

Puede configurar los tiempos de espera para cada uno de sus clientes de servicio mediante los apiCallAttemptTimeoutsetters apiCallTimeouty de. ClientOverrideConfiguration.Builder La apiCallTimeout configuración es la cantidad de tiempo que se tarda en permitir que el cliente complete la ejecución de una API llamada. La apiCallAttemptTimeout configuración es el tiempo que se debe esperar a que se complete cada HTTP solicitud (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 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 ejecución

Puede escribir código que intercepte la ejecución de sus API solicitudes y respuestas en diferentes partes del ciclo de vida de la solicitud o 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. AWS SDK for Java API