Konfiguration von Client-Endpunkten in der AWS SDK for Java 2.x

Das SDK for Java 2.x bietet mehrere Möglichkeiten, Dienstendpunkte zu konfigurieren. Ein Endpunkt ist die URL, die das SDK für API-Aufrufe verwendet. AWS-Services Standardmäßig bestimmt das SDK automatisch den geeigneten Endpunkt für jeden Dienst auf der Grundlage des von AWS-Region Ihnen konfigurierten. Es gibt jedoch Szenarien, in denen Sie diese Endpunkte möglicherweise anpassen oder überschreiben müssen:

Optionen für die Konfiguration von Endpunkten

Das AWS SDK for Java 2.x bietet mehrere Möglichkeiten zur Konfiguration von Endpunkten:

Code-interne Endpunktkonfiguration

Verwenden von endpointOverride

Der direkteste Weg, einen Endpunkt zu konfigurieren, ist die Verwendung der endpointOverride Methode im Service Client Builder. Diese Methode akzeptiert ein URI Objekt, das die benutzerdefinierte Endpunkt-URL darstellt.

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

Bei der Verwendung endpointOverride müssen Sie immer noch eine Region für den Client angeben, auch wenn der Endpunkt explizit festgelegt ist. Die Region wird zum Signieren von Anfragen verwendet.

Endpunkterkennung

Einige AWS-Services unterstützen die Endpunkterkennung, bei der das SDK automatisch den optimalen zu verwendenden Endpunkt ermitteln kann. Sie können diese Funktion mithilfe der endpointDiscoveryEnabled Methode im Service Client Builder aktivieren oder deaktivieren.

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

Endpunktkonfiguration auf Anforderungsebene

In einigen Fällen müssen Sie möglicherweise den Endpunkt für eine bestimmte Anfrage überschreiben, während Sie denselben Client für andere Anfragen mit dem Standardendpunkt verwenden. Der AWS SDK for Java 2.x unterstützt dies durch das Überschreiben von Anfragen.

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

Beachten Sie, dass das Überschreiben von Endpunkten auf Anforderungsebene begrenzt ist und möglicherweise nicht für alle Dienste oder Szenarien funktioniert. In den meisten Fällen wird empfohlen, die Endpunktkonfiguration auf Client-Ebene zu verwenden.

Konfiguration externer Endgeräte

Verwenden von -Umgebungsvariablen

Sie können Endpunkte mithilfe von Umgebungsvariablen konfigurieren. Das SDK unterstützt die dienstspezifische Endpunktkonfiguration mithilfe von Umgebungsvariablen im FormatAWS_ENDPOINT_URL_[SERVICE], in dem die Service-ID in Großbuchstaben [SERVICE] steht.

# 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
                

Sie können auch ein globales Endpunkt-URL-Präfix oder -Suffix mithilfe der folgenden Umgebungsvariablen festlegen:

Verwendung von JVM-Systemeigenschaften

Sie können Endpoints auch mithilfe der JVM-Systemeigenschaften konfigurieren. Das Format ähnelt Umgebungsvariablen, verwendet jedoch eine andere Namenskonvention.

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

Die globale Endpunktkonfiguration ist auch über die Systemeigenschaften verfügbar:

Verwenden Sie die gemeinsam genutzte Konfigurationsdatei AWS

Das unterstützt AWS SDK for Java 2.x auch die Endpunktkonfiguration über die gemeinsam genutzte AWS Konfigurationsdatei, die sich normalerweise unter ~/.aws/config (Linux/macOS) oder %USERPROFILE%\.aws\config (Windows) befindet. Informationen und Beispiele finden Sie im Referenzhandbuch AWS SDKs und im Tools-Referenzhandbuch.

Vorrang bei der Konfiguration

Wenn mehrere Endpunktkonfigurationen vorhanden sind, folgt das SDK dieser Rangfolge (von der höchsten zur niedrigsten):

Dienstspezifische Endpunktkonfiguration

Einige AWS-Services bieten zusätzliche Optionen für die Endpunktkonfiguration, die für diesen Dienst spezifisch sind. Nachfolgend sind einige Beispiele aufgeführt:

Amazon S3 S3-Endpunktkonfiguration

Amazon S3 unterstützt mehrere Endpunktkonfigurationen über die S3Configuration Klasse:

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

DynamoDB-Endpunktkonfiguration

Für DynamoDB möchten Sie vielleicht Endpoint Discovery verwenden oder zu Testzwecken eine lokale Verbindung zu DynamoDB herstellen:

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 unterstützt auch die Verwendung von kontobasierten Endpunkten, die Sie im Code oder mithilfe externer Einstellungen konfigurieren können. Das folgende Beispiel zeigt, wie Sie die Verwendung von kontobasierten Endpunkten im Code deaktivieren können, wenn Sie den Client erstellen (die Standardeinstellungen werden bevorzugt):

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

Bewährte Methoden

Beachten Sie bei der Konfiguration von Endpunkten im die folgenden AWS SDK for Java 2.x bewährten Methoden: