通过外部方式为AWS SDK for Java 2.x 配置服务客户端
许多配置设置可以通过代码以外的方式来处理。当您通过外部方式处理配置时,配置可以在同一个 Java 进程中应用于所有应用程序。大多数配置设置可以设置为环境变量、JVM 系统属性或在单独的共享 AWS config 文件中设置。共享 config 文件可以维护多组独立的设置(称为配置文件),以便为不同的环境或测试提供不同的配置。
大多数环境变量和共享 config 文件设置都已标准化,可在 AWS SDK 和工具之间共享,从而支持在不同编程语言和应用程序之间保持一致的功能。在大多数情况下,适用于 Java 的 SDK 可以使用的 JVM 系统属性与环境变量一一对应。
请参阅《AWS SDK 和工具参考指南》,了解如何通过这些方法配置应用程序,以及每个跨 SDK 设置的详细信息。要查看 SDK 可以从环境变量、JVM 系统属性或配置文件中解析的所有设置,请参阅《AWS SDK 和工具参考指南》中的设置参考。
用于客户端配置的配置提供程序链
SDK 会检查几个位置(或来源)以查找配置值。
-
在代码中或服务客户端本身设置的任何显式设置均优先于其他任何设置。
-
JVM 系统属性
-
有关设置 JVM 系统属性的详细信息,请参阅《AWS SDK 和工具参考指南中的如何设置 JVM 系统属性。
-
-
环境变量
-
有关设置环境变量的详细信息,请参阅《AWS SDK 和工具参考指南》中的环境变量。
-
请注意,您可以在不同作用域层级为 shell 配置环境变量:系统级、用户级,以及特定终端会话级。
-
-
共享
config文件和credentials文件-
有关设置这些文件的详细信息,请参阅《AWS SDK 和工具参考指南》中的共享
config和credentials文件。
-
-
最后使用 SDK 源代码本身提供的任何默认值。
-
某些属性(例如“Region”)没有默认值。您必须在代码、环境设置或共享
config文件中明确指定这些属性。如果 SDK 无法解析所需的配置,API 请求在运行时会失败。
-
除了这个通用配置链之外,适用于 Java 的 SDK 2.x 还使用专门的提供程序链,包括凭证提供程序链和 AWS 区域提供程序链。这些专门的链会添加其他提供程序,这些提供程序会考虑 SDK 的运行环境。例如,在容器或 EC2 实例中。
创建使用外部设置配置的服务客户端
您需要在应用程序中创建一个服务客户端才能与 AWS 服务通信。服务客户端是您与 AWS 服务建立连接的关键组件,它会处理所有复杂的通信细节,让您无需为此操心。它们会自动处理安全性、错误处理和重试等重要任务,让您可以专注于构建应用程序,而不是处理复杂的技术问题。
使用 create() 方法
如果您需要的所有配置设置都来自外部来源,则可以使用简单方法创建服务客户端:
S3Client s3Client = S3Client.create();
前面的代码段创建了一个 S3Client 实例。在创建过程中,SDK 会按照配置提供程序链依次查找所需的设置。SDK 找到某个设置值后,便会立即采用,即使链中的后续位置还存在该配置,也会忽略后续配置。
例如,假设用户通过设置系统属性 -Daws.region=us-west-2 来设置 AWS 区域的 JVM 设置。如果还设置了 AWS_REGION 环境变量,则其值将被忽略。
创建过程中还将使用默认区域提供程序链和默认凭证提供程序链。在链的某个地方,SDK 必须解析要使用的 AWS 区域,并找到使其能够为签名请求检索凭证的设置。如果 SDK 无法找到这些值,则客户端创建失败。
尽管您可以使用这个空的生成器模式来创建客户端,但当您想在代码中添加配置时,通常会使用这种模式。
适用于 Java 的 SDK 2.x 环境变量和 JVM 系统属性
除了大多数 AWS SDK 支持的跨 SDK 设置外,适用于 Java 的 SDK 2.x 还提供以下设置。
注意
这些环境变量和 JVM 系统属性主要用于高级使用案例、测试或特定部署场景。在大多数应用程序代码中,最好使用 SDK 的客户端生成器提供的编程配置选项,以便获得更好的类型安全性和 IDE 支持。
容器凭证提供程序环境变量
除了参考指南中记录的标准容器凭证环境变量外,SDK 还支持:
AWS_CONTAINER_SERVICE_ENDPOINT – 使用容器凭证提供程序时,此环境变量指定容器元数据服务的端点。
Java 系统属性:aws.containerServiceEndpoint
默认值:http://169.254.170.2
HTTP 客户端实现环境变量
SYNC_HTTP_SERVICE_IMPL – 明确标识 SDK 将使用的默认同步 HTTP 实现。当类路径上有多个实现,这种做法非常有用;因为实现发现需要对类路径进行扫描,这也是一种性能优化手段。
Java 系统属性:software.amazon.awssdk.http.service.impl
ASYNC_HTTP_SERVICE_IMPL – 明确标识 SDK 将使用的默认异步 HTTP 实现。当类路径上有多个实现,这种做法非常有用;因为实现发现需要对类路径进行扫描,这也是一种性能优化手段。
Java 系统属性:software.amazon.awssdk.http.async.service.impl