在 中設定用戶端端點 AWS SDK for Java 2.x - AWS SDK for Java 2.x
端點組態選項程式碼內端點組態請求層級端點組態外部端點組態組態優先順序服務特定的端點組態最佳實務

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 中設定用戶端端點 AWS SDK for Java 2.x

適用於 Java 的 SDK 2.x 提供多種方法來設定服務端點。端點是 SDK 用來呼叫 API 的 URL AWS 服務。根據預設，軟體開發套件會自動根據您設定的 AWS 區域 ，決定每個服務的適當端點。不過，在某些情況下，您可能需要自訂或覆寫這些端點：

  • 使用本機或第三方服務實作 （例如 LocalStack)

  • AWS 服務 透過代理或 VPC 端點連線至

  • 針對 Beta 版或發行前服務端點進行測試

端點組態選項

AWS SDK for Java 2.x 提供多種方法來設定端點：

  • 使用 服務用戶端建置器的程式碼內組態

  • 具有環境變數的外部組態

  • 具有 JVM 系統屬性的外部組態

  • 具有共用組態檔案 AWS 的外部組態

程式碼內端點組態

使用 endpointOverride

設定端點最直接的方式是在服務用戶端建置器上使用 endpointOverride方法。此方法接受代表自訂端點 URL 的URI物件。

範例 設定 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();

使用 時endpointOverride，即使已明確設定端點，您仍必須為用戶端指定區域。區域用於簽署請求。

端點探索

有些 AWS 服務 支援端點探索，其中 SDK 可以自動探索要使用的最佳端點。您可以使用服務用戶端建置器上的 endpointDiscoveryEnabled方法啟用或停用此功能。

範例 啟用 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();

請求層級端點組態

在某些情況下，您可能需要覆寫特定請求的端點，同時針對具有預設端點的其他請求使用相同的用戶端。透過請求覆寫 AWS SDK for Java 2.x 支援此功能。

範例 覆寫特定請求的端點

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

請注意，請求層級端點覆寫是有限的，可能無法適用於所有服務或案例。在大多數情況下，建議使用用戶端層級端點組態。

外部端點組態

使用 環境變數

您可以使用環境變數設定端點。SDK 透過格式為 的環境變數支援服務特定的端點組態AWS_ENDPOINT_URL_[SERVICE]，其中 [SERVICE]是大寫服務識別符。

範例 使用環境變數設定 S3 端點

# 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

您也可以使用下列環境變數設定全域端點 URL 字首或尾碼：

  • AWS_ENDPOINT_URL - 設定所有服務的全域端點

  • AWS_ENDPOINT_URL_PREFIX - 將字首新增至所有服務端點

  • AWS_ENDPOINT_URL_SUFFIX - 將尾碼新增至所有服務端點

使用 JVM 系統屬性

您也可以使用 JVM 系統屬性來設定端點。格式類似於環境變數，但使用不同的命名慣例。

範例 使用 JVM 系統屬性設定 S3 端點

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

全球端點組態也可透過系統屬性使用：

  • aws.endpointUrl - 設定所有服務的全域端點

  • aws.endpointUrl.prefix - 將字首新增至所有服務端點

  • aws.endpointUrl.suffix - 將尾碼新增至所有服務端點

使用共用 AWS 組態檔案

AWS SDK for Java 2.x 也支援透過共用 AWS 組態檔案的端點組態，通常位於 ~/.aws/config(Linux/macOS) 或 %USERPROFILE%\.aws\config(Windows)。如需相關資訊和範例，請參閱 AWS SDKs和工具參考指南。

組態優先順序

當有多個端點組態時，軟體開發套件會遵循此優先順序 （從最高到最低）：

  1. 請求層級覆寫 （如適用）

  2. 透過 的用戶端層級組態 endpointOverride

  3. 環境變數

  4. JVM 系統屬性

  5. 共用 AWS 組態檔案

  6. 根據設定的預設端點 AWS 區域

服務特定的端點組態

有些 AWS 服務 具有該服務特有的其他端點組態選項。以下是幾個範例：

Amazon S3 端點組態

Amazon S3 透過 S3Configuration類別支援多種端點組態：

  • dualstackEnabled - 啟用 IPv6 支援

  • accelerateModeEnabled - 啟用 S3 Transfer Acceleration

  • pathStyleAccessEnabled - 使用路徑樣式存取，而非虛擬託管樣式

  • useArnRegionEnabled - 將 ARN 中的區域用於跨區域請求

  • fipsModeEnabled - 將請求路由到符合 FIPS 標準的端點

範例 設定 S3-specific端點選項

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 端點組態

對於 DynamoDB，您可能想要使用端點探索或連線至 DynamoDB local 進行測試：

範例 連線至 DynamoDB 本機

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 也支援使用帳戶型端點，您可以在程式碼中或使用外部設定進行設定。下列範例顯示如何在建立用戶端時停用程式碼中以帳戶為基礎的端點 (偏好使用預設設定）：

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

最佳實務

在 中設定端點時 AWS SDK for Java 2.x，請考慮下列最佳實務：

  • 針對環境特定的端點使用外部組態 - 針對環境 （開發、測試、生產） 不同的端點使用環境變數、系統屬性或 AWS 組態檔案。

  • 將程式碼內組態用於應用程式特定的端點 — 將用戶端建置器的 endpointOverride方法用於應用程式設計特有的端點。

  • 一律指定區域 - 即使覆寫端點，也一律指定用於請求簽署的區域。

  • 使用全域端點覆寫時請小心—使用全域端點覆寫可能會影響所有服務，這可能不是您想要的服務。

  • 考量安全性影響 - 使用自訂端點時，請確保它們具有適當的安全措施，尤其是生產工作負載。