Configurar el cliente HTTP basado en CRT de AWS - AWS SDK for Java 2.x
Acceder a los clientes HTTP basados en CRT de AWSUtilizar y configurar un cliente HTTP basado en CRT de AWSEstablecer un cliente HTTP basado en CRT de AWS como predeterminadoConfiguración avanzadaCompatibilidad con HTTP/2Ejemplo de configuración proxy

Configurar el cliente HTTP basado en CRT de AWS

Los clientes HTTP basados en CRT de AWS incluyen el AwsCrtHttpClient síncrono y el AwsCrtAsyncHttpClient asíncrono. Los clientes HTTP basados en CRT de AWS ofrecen las siguientes ventajas de los clientes HTTP:

  • Tiempo de inicio del SDK más rápido

  • Ocupación de menos espacio de memoria

  • Tiempo de latencia reducido

  • Administración del estado de conexión

  • equilibrio de carga de DNS

Componentes basados en AWS CRT en el SDK

Los clientes HTTP basado en CRT de AWS, que se describen en este tema, y el cliente S3 basado en CRT de AWS son componentes diferentes del SDK.

Los clientes HTTP basados en CRT de AWS síncronos y asíncronos son implementaciones e interfaces de cliente HTTP de SDK y se utilizan para la comunicación HTTP general. Son alternativas a los otros clientes HTTP síncronos o asíncronos del SDK con ventajas adicionales.

El cliente de S3 basado en AWS CRT es una implementación de la interfaz S3AsyncClient y se utiliza para trabajar con el servicio de Amazon S3. Es una alternativa a la implementación de la interfaz S3AsyncClient basada en Java y ofrece varias ventajas.

Aunque ambos componentes utilizan bibliotecas del tiempo de ejecución común de AWS, los clientes TTP basados en CRT de AWS no utilizan la biblioteca aws-c-s3 y no admiten las funciones de API de carga multiparte de S3. El cliente S3 basado en AWS CRT, por el contrario, se creó específicamente para admitir las características de la API de carga multiparte de S3.

Acceder a los clientes HTTP basados en CRT de AWS

Antes de poder utilizar los clientes HTTP basados en CRT de AWS, añada el artefacto aws-crt-client con una versión mínima de 2.22.0 a las dependencias del proyecto.

Utilice una de las siguientes opciones para configurar el archivo pom.xml de Maven.

nota

Puede utilizar la Opción de jar específica de la plataforma si necesita reducir el tamaño de las dependencias de tiempo de ejecución, por ejemplo, si la aplicación se ejecuta en una función AWS Lambda.

Uber-jar option

De forma predeterminada, aws-crt-client utiliza un uber-jar de artefactos de AWS CRT que contiene archivos binarios para varias plataformas, incluidas Linux, Windows y macOS.

<project>
   <properties>
     <aws.sdk.java.version>2.29.10*</aws.sdk.java.version>
  </properties>
  <dependencyManagement>
   <dependencies>
      <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bom</artifactId>
        <version>${aws.sdk.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
   </dependencies>
  </dependencyManagement>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>aws-crt-client</artifactId>
   </dependency>
  </dependencies>
</project>

*Reemplace la versión que se muestra en rojo por la versión del SDK de Java que desee utilizar. Busque las últimas novedades sobre Maven Central.

Platform-specific jar option

Para restringir el tiempo de ejecución de Java a la versión específica de la plataforma de la biblioteca de CRT de AWS, realice los siguientes cambios en la opción Uber-jar.

  • Añada un elemento de exclusions al artefacto aws-crt-client del SDK. Esta exclusión impide que el SDK utilice el uber-jar de AWS CRT de forma transitiva.

  • Agregue un elemento de dependencia para la versión específica de la plataforma AWS CRT que necesite. Consulte a continuación los Pasos para determinar la versión del artefacto de AWS CRT para determinar la versión correcta.

<project>
   <properties>
     <aws.sdk.java.version>2.29.101</aws.sdk.java.version>
  </properties>
   <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>software.amazon.awssdk</groupId>
                <artifactId>bom</artifactId>
                <version>${aws.sdk.java.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>aws-crt-client</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>software.amazon.awssdk.crt</groupId>
                    <artifactId>aws-crt</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.31.32</version>
            <classifier>linux-x86_643</classifier>
        </dependency>
    </dependencies>

1Reemplace la versión que se muestra en rojo por la versión del SDK de Java que desee utilizar. Busque las últimas novedades sobre Maven Central.

2Reemplace la versión de software.amazon.awssdk.crt:aws-crt que proporcionaría la Opción Uber-jar. Consulte los siguientes Pasos para determinar la versión del artefacto de AWS CRT.

3Reemplace el valor de classifier por uno para su plataforma. Consulte la página de GitHub de AWS CRT para Java para obtener una lista de los valores disponibles.

Pasos para determinar la versión del artefacto de AWS CRT.

Siga estos pasos para determinar la versión del artefacto de AWS CRT que es compatible con la versión del SDK para Java que está utilizando.

  1. Configure el archivo pom.xml como se muestra en la Opción Uber-jar. Esta configuración permite ver qué versión de software.amazon.awssdk.crt:aws-crt del SDK está incluida de forma predeterminada.

  2. En la raíz del proyecto (en el mismo directorio que el archivo pom.xml), ejecute el siguiente comando de Maven:

    mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt

    Maven puede realizar otras acciones, pero al final debería ver el resultado de la consola de la dependencia de software.amazon.awssdk.crt:aws-crt que utiliza el SDK de forma transitiva. En el siguiente fragmento de código se muestra un ejemplo de resultado basado en una versión del SDK de 2.29.10:

    [INFO] org.example:yourProject:jar:1.0-SNAPSHOT
[INFO] \- software.amazon.awssdk:aws-crt-client:jar:2.29.10:compile
[INFO]    \- software.amazon.awssdk.crt:aws-crt:jar:0.31.3:compile

  3. Utilice la versión que muestra la consola para el artefacto de software.amazon.awssdk.crt:aws-crt. En este caso, añada 0.31.3 al archivo pom.xml.

Utilizar y configurar un cliente HTTP basado en CRT de AWS

Puede configurar un cliente HTTP basado en CRT de AWS junto con la creación de un cliente de servicio, o configurar una sola instancia para compartirla entre varios clientes de servicio.

Con cualquiera de estos enfoques, utilice un creador para configurar las propiedades de la instancia de cliente HTTP basada en CRT de AWS.

Práctica recomendada: dedicar una instancia de a un cliente de servicio

Si necesita configurar una instancia de un cliente HTTP AWS basado en CRT, le recomendamos que dedique la instancia y la cree junto con el cliente de servicio. Puede hacerlo con el método httpClientBuilder del generador del cliente del servicio. De esta forma, el SDK administra el ciclo de vida del cliente HTTP, lo que ayuda a evitar posibles pérdidas de memoria si la instancia del cliente HTTP basado en CRT de AWS no se cierra cuando ya no se necesita.

En el siguiente ejemplo se crea un cliente de servicio S3 y se configura un cliente HTTP basado en CRT de AWS con valores connectionTimeout y maxConcurrency.

Synchronous client

Importaciones

import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

Código de

// Singleton: Use s3Client for all requests.
S3Client s3Client = S3Client.builder()
    .httpClientBuilder(AwsCrtHttpClient
        .builder()
        .connectionTimeout(Duration.ofSeconds(3))
        .maxConcurrency(100))
    .build();

// Perform work with the s3Client.

// Requests completed: Close the s3Client.
s3Client.close();
Asynchronous client

Importaciones

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;

Código de

// Singleton: Use s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClientBuilder(AwsCrtAsyncHttpClient
        .builder()
        .connectionTimeout(Duration.ofSeconds(3))
        .maxConcurrency(100))
    .build();

// Perform work with the s3AsyncClient.

// Requests completed: Close the s3AsyncClient.
s3AsyncClient.close();

Enfoque alternativo: compartir una instancia

Para reducir el uso de recursos y memoria en su aplicación, puede configurar un cliente HTTP basado en CRT de AWS y compartirlo entre varios clientes de servicio. El grupo de conexiones HTTP se compartirá, lo que reduce el uso de recursos.

nota

Al compartir una instancia de cliente HTTP basado en CRT de AWS, es preciso cerrarla cuando esté lista para ser eliminada. El SDK no cerrará la instancia cuando el cliente del servicio esté cerrado.

En el siguiente ejemplo, se configura una instancia de cliente HTTP basado en CRT de AWS con valores connectionTimeout y maxConcurrency. La instancia configurada se pasa al método httpClient del creador de cada cliente de servicio. Cuando los clientes de servicio y el cliente HTTP ya no son necesarios, se cierran de forma explícita. El cliente HTTP se cierra en último lugar.

Synchronous client

Importaciones

import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

Código de

// Create an AwsCrtHttpClient shared instance.
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(3))
    .maxConcurrency(100)
    .build();

// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client = S3Client.builder()
    .httpClient(crtHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.crea
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
    .httpClient(crtHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.crea
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
crtHttpClient.close();  // Explicitly close crtHttpClient.
Asynchronous client

Importaciones

import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;

Código de

// Create an AwsCrtAsyncHttpClient shared instance.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(3))
    .maxConcurrency(100)
    .build();

// Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClient(crtAsyncHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder()
    .httpClient(crtAsyncHttpClient)
    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
    .defaultsMode(DefaultsMode.IN_REGION)
    .region(Region.US_EAST_1)
    .build();

// Requests completed: Close all service clients.
s3AsyncClient.close();
dynamoDbAsyncClient.close();
crtAsyncHttpClient.close();  // Explicitly close crtAsyncHttpClient.

Establecer un cliente HTTP basado en CRT de AWS como predeterminado

Puede configurar su archivo de compilación de Maven para que el SDK utilice un cliente HTTP basado en CRT de AWS como cliente HTTP predeterminado para los clientes de servicio.

Para ello, añada un elemento exclusions con las dependencias predeterminadas del cliente HTTP a cada artefacto del cliente de servicio.

En el siguiente ejemplo pom.xml, el SDK usa un cliente HTTP basado en CRT de AWS para los servicios de S3. Si el cliente de servicio de su código es un S3AsyncClient, el SDK utiliza AwsCrtAsyncHttpClient. Si el cliente de servicio es un S3Client, el SDK utiliza AwsCrtHttpClient. Con esta configuración, el cliente HTTP asíncrono predeterminado basado en Netty y el HTTP síncrono predeterminado basado en Apache no están disponibles.

<project>
   <properties>
     <aws.sdk.version>VERSION</aws.sdk.version>
  </properties>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>s3</artifactId>
      <version>${aws.sdk.version}</version>
      <exclusions>
         <exclusion>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>netty-nio-client</artifactId>
         </exclusion>
         <exclusion>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>apache-client</artifactId>
         </exclusion>
      </exclusions>
   </dependency>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>aws-crt-client</artifactId>
   </dependency>
  </dependencies>
</project>

Visite el repositorio central de Maven para ver el valor de la VERSIÓN más reciente.

nota

Si se declaran varios clientes de servicio en un archivo pom.xml, todos requieren el elemento XML exclusions.

Utilizar una propiedad del sistema Java

Para usar los clientes HTTP basados en CRT de AWS como HTTP predeterminado para su aplicación, puede establecer la propiedad del sistema Java software.amazon.awssdk.http.async.service.impl en un valor de software.amazon.awssdk.http.crt.AwsCrtSdkHttpService.

Para configurarlo durante el inicio de la aplicación, ejecute un comando similar al siguiente.

java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\
software.amazon.awssdk.http.crt.AwsCrtSdkHttpService

Use el siguiente fragmento de código para establecer la propiedad del sistema en el código de la aplicación.

System.setProperty("software.amazon.awssdk.http.async.service.impl",
"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");
nota

Debe añadir una dependencia al artefacto aws-crt-client del archivo poml.xml cuando utilice una propiedad del sistema para configurar el uso de los clientes HTTP basados en CRT de AWS.

Configuración avanzada de clientes HTTP basados en CRT de AWS

Puede usar varios ajustes de configuración de los clientes HTTP basados en CRT de AWS, incluida la configuración del estado de la conexión y el tiempo máximo de inactividad. Puede revisar las opciones de configuración disponibles para el AwsCrtAsyncHttpClient. Puede configurar las mismas opciones para AwsCrtHttpClient.

Configuración del estado de conexión

Puede configurar la configuración del estado de la conexión para los clientes HTTP basados en CRT de AWS mediante el método connectionHealthConfiguration del creador de clientes HTTP.

En el siguiente ejemplo, se crea un cliente de servicio S3 que utiliza una instancia de cliente HTTP basado en CRT de AWS configurada con una configuración de mantenimiento de la conexión y un tiempo máximo de inactividad para las conexiones.

Synchronous client

Importaciones

import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

Código de

// Singleton: Use the s3Client for all requests.
S3Client s3Client = S3Client.builder()
    .httpClientBuilder(AwsCrtHttpClient
        .builder()
        .connectionHealthConfiguration(builder -> builder
            .minimumThroughputInBps(32000L)
            .minimumThroughputTimeout(Duration.ofSeconds(3)))
        .connectionMaxIdleTime(Duration.ofSeconds(5)))
    .build();

// Perform work with s3Client.

// Requests complete: Close the service client.
s3Client.close();
Asynchronous client

Importaciones

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;

Código de

// Singleton: Use the s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClientBuilder(AwsCrtAsyncHttpClient
        .builder()
        .connectionHealthConfiguration(builder -> builder
            .minimumThroughputInBps(32000L)
            .minimumThroughputTimeout(Duration.ofSeconds(3)))
        .connectionMaxIdleTime(Duration.ofSeconds(5)))
    .build();

// Perform work with s3AsyncClient.

// Requests complete: Close the service client.
s3AsyncClient.close();

Compatibilidad con HTTP/2

El protocolo HTTP/2 aún no es compatible con el cliente HTTP basado en CRT de AWS, pero está previsto para una versión futura.

Mientras tanto, si utiliza clientes de servicio que requieren compatibilidad con HTTP/2, como KinesisaSyncClient o TranscribeStreamingAsyncClient, considere la posibilidad de utilizar NettyNioAsynchTTPClient en su lugar.

Ejemplo de configuración proxy

El siguiente fragmento de código muestra el uso de ProxyConfiguration.Builder que se utiliza para configurar el proxy en el código.

Synchronous client

Importaciones

import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;

Código de

SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .host("myproxy")
        .port(1234)
        .username("username")
        .password("password")
        .nonProxyHosts(Set.of("localhost", "host.example.com"))
        .build())
    .build();
Asynchronous client

Importaciones

import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;

Código de

SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .host("myproxy")
        .port(1234)
        .username("username")
        .password("password")
        .nonProxyHosts(Set.of("localhost", "host.example.com"))
        .build())
    .build();

Las propiedades del sistema Java equivalentes para la configuración del proxy se muestran en el siguiente fragmento de línea de comandos.

$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
importante

Para utilizar cualquiera de las propiedades del sistema proxy HTTPS, la propiedad scheme debe estar configurada en código para https. Si la propiedad del esquema no está configurada en el código, el esquema predeterminado es HTTP y el SDK solo busca las propiedades del sistema http.*.

La configuración equivalente que usa variables de entorno es:

// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"

// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
    .proxyConfiguration(ProxyConfiguration.builder()
        .scheme("https")
        .useSystemPropertyValues(Boolean.FALSE)
        .build())
    .build();

// Run the application.
// $ java -cp ... App