Configuración de los puntos de conexión del cliente en AWS SDK for Java 2.x

El SDK para Java 2.x proporciona varias formas de configurar puntos de conexión de servicio. Un punto de conexión es la URL que el SDK utiliza para realizar llamadas a la API a Servicios de AWS. De forma predeterminada, el SDK determina automáticamente el punto de conexión apropiado para cada servicio en función de la Región de AWS que haya configurado. No obstante, hay situaciones en las que tal vez sea preciso personalizar o anular estos puntos de conexión:

• Trabajo con implementaciones de servicio locales o de terceros (como LocalStack)

• Conexión con Servicios de AWS a través de un proxy o un punto de conexión de VPC

• Pruebas con puntos de conexión de servicio en versión beta o previa al lanzamiento

Opciones de configuración de puntos de conexión

AWS SDK for Java 2.x proporciona varias formas de configurar puntos de conexión:

• Configuración integrada en el código mediante el compilador de clientes de servicios

• Configuración externa con variables de entorno

• Configuración externa con propiedades del sistema JVM

• Configuración externa con un archivo de configuración de AWS compartido

Configuración de puntos de conexión integrados en el código

Uso de endpointOverride

La forma más directa de configurar un punto de conexión es utilizando el método endpointOverride en el compilador de clientes de servicio. Este método acepta un objeto URI que representa la URL del punto de conexión personalizado.

ejemplo Configuración de un punto de conexión personalizado para un cliente de Amazon S3

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .endpointOverride(URI.create("https://my-custom-s3-endpoint.example.com"))
        .build();
                

Al usar endpointOverride, debe seguir especificando una región para el cliente, aunque el punto de conexión se haya establecido de forma explícita. La región se usa para firmar solicitudes.

Detección de puntos de enlace

Algunas Servicios de AWS admiten detección de puntos de conexión, en la que el SDK puede detectar automáticamente el punto de conexión óptimo para su uso. Puede habilitar o deshabilitar esta característica mediante el método endpointDiscoveryEnabled en el compilador de clientes de servicio.

ejemplo Habilitación de la detección de puntos de conexión para un cliente de DynamoDB

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .region(Region.US_WEST_2)
        .endpointDiscoveryEnabled(true)
        .build();
                

Configuración de puntos de conexión de nivel de solicitud

En algunos casos, es posible que tenga que anular el punto de conexión para una solicitud específica y utilizar el mismo cliente para otras solicitudes con el punto de conexión predeterminado. AWS SDK for Java 2.x ofrece esta opción mediante la anulación de solicitudes.

ejemplo Anulación del punto de conexión para una solicitud específica

import software.amazon.awssdk.core.SdkRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.http.SdkHttpRequest;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .build();

// Create a request
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
        .bucket("amzn-s3-demo-bucket")
        .key("my-key")
        .overrideConfiguration(c -> c.putHeader("Host", "custom-endpoint.example.com"))
        .build();

// Execute the request with the custom endpoint
s3.getObject(getObjectRequest);
            

Tenga en cuenta que las anulaciones de puntos de conexión en el nivel de solicitud son limitadas y es posible que no funcionen en todos los servicios o escenarios. En la mayoría de los casos, se recomienda utilizar una configuración de punto de conexión en el nivel de cliente.

Configuración de puntos de conexión externos

Uso de variables de entorno

Puede configurar puntos de conexión mediante variables de entorno. El SDK admite la configuración de puntos de conexión específicos del servicio mediante variables de entorno con el formato AWS_ENDPOINT_URL_[SERVICE], donde [SERVICE] es el identificador de servicio en mayúscula.

ejemplo Configuración de un punto de conexión de S3 mediante variables de entorno

# For Linux/macOS
export AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com

# For Windows
set AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com
                

También puede establecer un prefijo o sufijo de URL de punto de conexión global mediante las siguientes variables de entorno:

• AWS_ENDPOINT_URL: establece un punto de conexión global para todos los servicios

• AWS_ENDPOINT_URL_PREFIX: añade un prefijo a todos los puntos de conexión de servicio

• AWS_ENDPOINT_URL_SUFFIX: añade un sufijo a todos los puntos de conexión de servicio

Uso de las propiedades del sistema JVM

También puede configurar puntos de conexión mediante las propiedades del sistema JVM. El formato es similar al de las variables de entorno, pero utiliza una convención de nomenclatura diferente.

ejemplo Configuración de un punto de conexión de S3 utilizando las propiedades del sistema JVM

java -Daws.endpointUrl.s3=https://my-custom-s3-endpoint.example.com -jar your-application.jar
                

La configuración de puntos de conexión globales también está disponible a través de las propiedades del sistema:

• aws.endpointUrl: establece un punto de conexión global para todos los servicios

• aws.endpointUrl.prefix: añade un prefijo a todos los puntos de conexión de servicio

• aws.endpointUrl.suffix: añade un sufijo a todos los puntos de conexión de servicio

Uso del archivo de configuración de AWS compartido

AWS SDK for Java 2.x también admite la configuración de puntos de conexión a través del archivo de configuración de AWS compartido, que normalmente se encuentra en ~/.aws/config (Linux/macOS) o %USERPROFILE%\.aws\config (Windows). Consulte la Guía de referencia de los SDK y las herramientas de AWS para obtener información y ejemplos.

Prioridad de configuración

Cuando hay varias configuraciones de punto de conexión, el SDK sigue este orden de prioridad (de mayor a menor):

1. Anulaciones de nivel de solicitud (cuando proceda)

2. Configuración de nivel de cliente a través de endpointOverride

3. Variables de entorno

4. Propiedades del sistema JVM

5. Archivo de configuración de AWS compartido

6. Puntos de conexión predeterminados en función de la Región de AWS configurada

Configuración de puntos de conexión específicos del servicio

Algunos Servicios de AWS tienen opciones adicionales de configuración de puntos de conexión específicas para ese servicio. A continuación se muestran algunos ejemplos:

Configuración de puntos de conexión de Amazon S3

Amazon S3 admite varias configuraciones de puntos de conexión a través de la clase S3Configuration:

• dualstackEnabled: habilita compatibilidad con IPv6

• accelerateModeEnabled: habilita la aceleración de transferencias de S3

• pathStyleAccessEnabled: utiliza el estilo de acceso por ruta en lugar del estilo de alojamiento virtual

• useArnRegionEnabled: utiliza la región de un ARN para las solicitudes entre regiones

• fipsModeEnabled: enruta solicitudes a puntos de conexión que cumplen con FIPS

ejemplo Configuración de opciones de punto de conexión específicas de S3

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .serviceConfiguration(S3Configuration.builder()
                .accelerateModeEnabled(true)
                .dualstackEnabled(true)
                .pathStyleAccessEnabled(false)
                .fipsModeEnabled(true)
                .build())
        .build();
                

Configuración de puntos de conexión de DynamoDB

En el caso de DynamoDB, conviene utilizar la detección de puntos de conexión o conectarse a DynamoDB local para realizar pruebas:

ejemplo Conexión a DynamoDB local

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import java.net.URI;

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .endpointOverride(URI.create("http://localhost:8000"))
        // The region is meaningless for DynamoDB local but required for the client builder.
        .region(Region.US_WEST_2)
        .build();
                

DynamoDB también admite el uso de puntos de conexión basados en cuentas, que se pueden configurar en código o mediante ajustes externos. El siguiente ejemplo muestra cómo deshabilitar en el código el uso de puntos de conexión basados en cuentas al crear el cliente (la configuración predeterminada es la preferida):

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
    .region(Region.US_EAST_1)
    .accountIdEndpointMode(AccountIdEndpointMode.DISABLED)
    .build();

Prácticas recomendadas

Al configurar puntos de conexión en AWS SDK for Java 2.x, tenga en cuenta estas prácticas recomendadas:

• Utilice una configuración externa para puntos de conexión específicos del entorno: utilice variables de entorno, propiedades del sistema o el archivo de configuración de AWS para puntos de conexión que varían de un entorno a otro (desarrollo, pruebas, producción).

• Utilice configuración integrada en el código para puntos de conexión específicos de la aplicación: utilice el método endpointOverride del compilador de clientes para puntos de conexión específicos del diseño de la aplicación.

• Especifique siempre una región: incluso al anular puntos de conexión, especifique siempre una región tal como se utiliza para firmar solicitudes.

• Tenga cuidado con las anulaciones de puntos de conexión globales: el uso de anulaciones de puntos de conexión globales puede afectar a todos los servicios, y quizá no sea esa su intención.

• Tenga en cuenta las implicaciones de seguridad: cuando utilice puntos de conexión personalizados, asegúrese de que cuenten con las medidas de seguridad adecuadas, especialmente para cargas de trabajo de producción.