Configurazione degli endpoint client in AWS SDK for Java 2.x

L'SDK for Java 2.x offre diversi modi per configurare gli endpoint del servizio. Un endpoint è l'URL utilizzato dall'SDK per effettuare chiamate API. Servizi AWS Per impostazione predefinita, l'SDK determina automaticamente l'endpoint appropriato per ogni servizio in base a quello Regione AWS che hai configurato. Tuttavia, ci sono scenari in cui potresti dover personalizzare o sostituire questi endpoint:

Opzioni di configurazione degli endpoint

AWS SDK for Java 2.x Fornisce diversi modi per configurare gli endpoint:

Configurazione degli endpoint incorporata nel codice

Uso di endpointOverride

Il modo più diretto per configurare un endpoint consiste nell'utilizzare il endpointOverride metodo sul service client builder. Questo metodo accetta un URI oggetto che rappresenta l'URL dell'endpoint personalizzato.

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

Durante l'utilizzoendpointOverride, devi comunque specificare una regione per il client, anche se l'endpoint viene impostato in modo esplicito. La regione viene utilizzata per firmare le richieste.

Rilevamento di endpoint

Alcuni Servizi AWS supportano l'endpoint discovery, in cui l'SDK può scoprire automaticamente l'endpoint ottimale da utilizzare. È possibile abilitare o disabilitare questa funzionalità utilizzando il endpointDiscoveryEnabled metodo del service client builder.

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

Configurazione degli endpoint a livello di richiesta

In alcuni casi, potrebbe essere necessario sovrascrivere l'endpoint per una richiesta specifica mentre si utilizza lo stesso client per altre richieste con l'endpoint predefinito. Lo AWS SDK for Java 2.x supporta tramite l'override delle richieste.

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

Tieni presente che le sostituzioni degli endpoint a livello di richiesta sono limitate e potrebbero non funzionare per tutti i servizi o gli scenari. Nella maggior parte dei casi, si consiglia di utilizzare la configurazione degli endpoint a livello di client.

Configurazione degli endpoint esterni

Utilizzo delle variabili di ambiente

È possibile configurare gli endpoint utilizzando variabili di ambiente. L'SDK supporta la configurazione degli endpoint specifici del servizio tramite variabili di ambiente nel formatoAWS_ENDPOINT_URL_[SERVICE], dove [SERVICE] è l'identificatore di servizio in maiuscolo.

# 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
                

Puoi anche impostare un prefisso o suffisso URL globale dell'endpoint utilizzando le seguenti variabili di ambiente:

Utilizzo delle proprietà del sistema JVM

È inoltre possibile configurare gli endpoint utilizzando le proprietà del sistema JVM. Il formato è simile alle variabili di ambiente ma utilizza una convenzione di denominazione diversa.

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

La configurazione globale degli endpoint è disponibile anche tramite le proprietà del sistema:

Utilizzo del file di configurazione condiviso AWS

Supporta AWS SDK for Java 2.x anche la configurazione degli endpoint tramite il file di AWS configurazione condiviso, in genere situato in ~/.aws/config (Linux/macOS) o (Windows). %USERPROFILE%\.aws\config Consulta la guida di riferimento AWS SDKs and Tools per informazioni ed esempi.

Precedenza della configurazione

Quando sono presenti più configurazioni di endpoint, l'SDK segue questo ordine di precedenza (dal più alto al più basso):

Configurazione degli endpoint specifica del servizio

Alcuni Servizi AWS dispongono di opzioni di configurazione degli endpoint aggiuntive specifiche per quel servizio. Di seguito si riportano alcuni esempi:

Configurazione degli endpoint Amazon S3

Amazon S3 supporta diverse configurazioni di endpoint tramite la classe: S3Configuration

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

Configurazione degli endpoint DynamoDB

Per DynamoDB, potresti voler utilizzare l'endpoint discovery o connetterti a DynamoDB locale per i test:

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 supporta anche l'uso di endpoint basati su account, che possono essere configurati in codice o utilizzando impostazioni esterne. L'esempio seguente mostra come disabilitare l'uso degli endpoint basati su account nel codice quando si crea il client (sono preferite le impostazioni predefinite):

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

Best practice

Quando configuri gli endpoint in AWS SDK for Java 2.x, considera queste best practice: