在中配置客户端终端节点 AWS SDK for Java 2.x - AWS SDK for Java 2.x
端点配置选项代码内端点配置请求级端点配置外部端点配置配置优先级特定于服务的端点配置最佳实践

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

在中配置客户端终端节点 AWS SDK for Java 2.x

适用于 Java 的 SDK 2.x 提供了多种配置服务端点的方法。终端节点是软件开发工具包用来进行 API 调用的网址 AWS 服务。默认情况下，SDK 会根据 AWS 区域 您的配置自动为每项服务确定合适的终端节点。但是，在某些情况下，您可能需要自定义或覆盖以下端点：

  • 使用本地或第三方服务实现（例如 LocalStack）

  • AWS 服务 通过代理或 VPC 终端节点连接

  • 针对测试版或预发布服务端点进行测试

端点配置选项

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 信息和示例，请参阅和工具参考指南。

配置优先级

当存在多个端点配置时，SDK 遵循以下优先顺序（从高到低）：

  1. 请求级别覆盖（如果适用）

  2. 通过以下方式进行客户端级配置 endpointOverride

  3. 环境变量

  4. JVM 系统属性

  5. 共享 AWS 配置文件

  6. 基于配置的默认终端节点 AWS 区域

特定于服务的端点配置

有些还 AWS 服务 具有特定于该服务的额外端点配置选项。下面是几个示例：

亚马逊 S3 终端节点配置

Amazon S3 通过该S3Configuration类支持多种终端节点配置：

  • dualstackEnabled-启用 IPv6 支持

  • accelerateModeEnabled-启用 S3 传输加速

  • pathStyleAccessEnabled-使用路径式访问而不是虚拟托管样式

  • useArnRegionEnabled-使用 ARN 中的区域进行跨区域请求

  • fipsModeEnabled-将请求路由到符合 FIPS 标准的端点

例 配置特定于 S3 的端点选项

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 本地进行测试：

例 正在本地连接 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方法来处理特定于应用程序设计的端点。

  • 始终指定区域-即使覆盖终端节点，也要始终指定用于请求签名的区域。

  • 请@@ 谨慎使用全局终端节点覆盖-使用全局终端节点覆盖可能会影响所有服务，而这可能不是您想要的。

  • 考虑安全影响 — 使用自定义终端节点时，请确保它们有适当的安全措施，尤其是对于生产工作负载。