Configuration des points de terminaison clients dans le AWS SDK for Java 2.x

Le SDK pour Java 2.x propose plusieurs méthodes pour configurer les points de terminaison de service. Un point de terminaison est l'URL que le SDK utilise pour effectuer des appels d' Services AWS API. Par défaut, le SDK détermine automatiquement le point de terminaison approprié pour chaque service en fonction de celui que Région AWS vous avez configuré. Cependant, il existe des scénarios dans lesquels vous devrez peut-être personnaliser ou remplacer ces points de terminaison :

Options de configuration des terminaux

AWS SDK for Java 2.x Il propose plusieurs méthodes pour configurer les points de terminaison :

Configuration du point de terminaison intégrée au code

Utiliser endpointOverride

Le moyen le plus direct de configurer un point de terminaison consiste à utiliser la endpointOverride méthode du générateur de clients de services. Cette méthode accepte un URI objet représentant l'URL du point de terminaison personnalisé.

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

Lors de l'utilisationendpointOverride, vous devez toujours spécifier une région pour le client, même si le point de terminaison est défini explicitement. La région est utilisée pour signer les demandes.

Découverte du points de terminaison

Certains Services AWS prennent en charge la découverte des terminaux, grâce à laquelle le SDK peut automatiquement découvrir le point de terminaison optimal à utiliser. Vous pouvez activer ou désactiver cette fonctionnalité à l'aide de la endpointDiscoveryEnabled méthode du générateur de clients de services.

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

Configuration du point de terminaison au niveau de la demande

Dans certains cas, vous devrez peut-être remplacer le point de terminaison pour une demande spécifique tout en utilisant le même client pour d'autres demandes avec le point de terminaison par défaut. Cela est pris AWS SDK for Java 2.x en charge par le biais de remplacements de demandes.

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

Notez que les remplacements de point de terminaison au niveau de la demande sont limités et peuvent ne pas fonctionner pour tous les services ou scénarios. Dans la plupart des cas, il est recommandé d'utiliser une configuration de point de terminaison au niveau du client.

Configuration du point de terminaison externe

Utilisation des variables d’environnement

Vous pouvez configurer les points de terminaison à l'aide de variables d'environnement. Le SDK prend en charge la configuration des points de terminaison spécifiques au service par le biais de variables d'environnement au formatAWS_ENDPOINT_URL_[SERVICE], où [SERVICE] est l'identifiant de service en majuscules.

# 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
                

Vous pouvez également définir un préfixe ou un suffixe d'URL de point de terminaison global à l'aide des variables d'environnement suivantes :

Utilisation des propriétés du système JVM

Vous pouvez également configurer les points de terminaison à l'aide des propriétés du système JVM. Le format est similaire à celui des variables d'environnement mais utilise une convention de dénomination différente.

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

La configuration globale du point de terminaison est également disponible via les propriétés du système :

Utilisation du fichier de AWS configuration partagé

AWS SDK for Java 2.x Il prend également en charge la configuration des terminaux via le fichier de AWS configuration partagé, généralement situé dans ~/.aws/config (Linux/macOS) ou %USERPROFILE%\.aws\config (Windows). Consultez le guide de référence AWS SDKs et des outils pour obtenir des informations et des exemples.

Ordre de priorité de configuration

Lorsque plusieurs configurations de point de terminaison sont présentes, le SDK suit cet ordre de priorité (du plus élevé au plus bas) :

Configuration du point de terminaison spécifique au service

Certains Services AWS proposent des options de configuration de point de terminaison supplémentaires spécifiques à ce service. Voici quelques exemples:

Configuration du point de terminaison Amazon S3

Amazon S3 prend en charge plusieurs configurations de point de terminaison par le biais de la S3Configuration classe :

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

Configuration du point de terminaison DynamoDB

Pour DynamoDB, vous pouvez utiliser la découverte des points de terminaison ou vous connecter à DynamoDB local pour tester :

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 prend également en charge l'utilisation de points de terminaison basés sur des comptes, que vous pouvez configurer dans le code ou à l'aide de paramètres externes. L'exemple suivant montre comment désactiver l'utilisation de points de terminaison basés sur un compte dans le code lorsque vous créez le client (les paramètres par défaut sont préférés) :

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

Bonnes pratiques

Lorsque vous configurez des points de terminaison dans le AWS SDK for Java 2.x, tenez compte des meilleures pratiques suivantes :