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

El SDK for Java 2.x proporciona varias formas de configurar los puntos finales de servicio. Un punto final es la URL que el SDK utiliza para realizar llamadas a la API. Servicios de AWS De forma predeterminada, el SDK determina automáticamente el punto final apropiado para cada servicio en función del Región de AWS que hayas configurado. Sin embargo, hay situaciones en las que es posible que deba personalizar o anular estos puntos finales:

Opciones de configuración de terminales

AWS SDK for Java 2.x proporciona varias formas de configurar los puntos finales:

Configuración de punto final integrada en el código

Uso de endpointOverride

La forma más directa de configurar un punto final es mediante el endpointOverride método del generador de clientes de servicios. Este método acepta un URI objeto que representa la URL del punto final personalizado.

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 usarloendpointOverride, debe seguir especificando una región para el cliente, aunque el punto final se haya establecido de forma explícita. La región se usa para firmar solicitudes.

Detección de puntos de conexión

Algunas Servicios de AWS admiten la detección de puntos finales, con lo que el SDK puede detectar automáticamente el punto final óptimo para su uso. Puede activar o desactivar esta función mediante el endpointDiscoveryEnabled método del generador de clientes de servicios.

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 finales a nivel de solicitud

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

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("my-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 finales a 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 final a nivel de cliente.

Configuración de punto final externo

Uso de variables de entorno

Puede configurar los puntos finales mediante variables de entorno. El SDK admite la configuración de puntos finales específicos del servicio mediante variables de entorno en el formatoAWS_ENDPOINT_URL_[SERVICE], donde [SERVICE] aparece el identificador del servicio en mayúscula.

# 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 final global mediante las siguientes variables de entorno:

Uso de las propiedades del sistema JVM

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

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

La configuración global del punto final también está disponible a través de las propiedades del sistema:

Uso del archivo de configuración compartido AWS

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

Prioridad de configuración

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

Configuración de puntos finales específicos del servicio

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

Configuración del punto de conexión Amazon S3

Amazon S3 admite varias configuraciones de puntos de conexión de toda la S3Configuration clase:

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, es posible que desee utilizar la detección de puntos finales o conectarse a DynamoDB local para realizar pruebas:

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 el uso de puntos de enlace basados en cuentas en el código al crear el cliente (se prefiere la configuración predeterminada):

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

Prácticas recomendadas

Al configurar los puntos finales en el AWS SDK for Java 2.x, tenga en cuenta estas prácticas recomendadas: