Amazon SDKs 和工具设置参考 - Amazon SDKs 和工具
创建服务客户端设置的优先级了解本指南的设置页面Config文件设置列表Credentials文件设置列表环境变量列表JVM 系统属性列表
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

Amazon SDKs 和工具设置参考

SDKs 提供特定于语言的内容 APIs 。 Amazon Web Services 服务它们负责成功进行 API 调用所需的一些繁重工作，包括身份验证、重试行为等。为此， SDKs 他们需要制定灵活的策略来获取用于您的请求的凭证，维护用于每项服务的设置，以及获取用于全局设置的值。

您可以在以下各节中找到有关配置设置的详细信息：

创建服务客户端

要以编程方式访问 Amazon Web Services 服务， SDKs 请分别 Amazon Web Services 服务使用客户端 class/object 。例如，如果您的应用程序需要访问亚马逊 EC2，则您的应用程序会创建一个 Amazon EC2 客户端对象来与该服务接口。然后，您可以使用服务客户端向该 Amazon Web Services 服务发出请求。在大多数情况下 SDKs，服务客户端对象是不可变的，因此您必须为向其发出请求的每个服务创建一个新的客户端，并使用不同的配置向同一服务发出请求。

设置的优先级

全局设置配置了大多数 SDKs 人支持并具有广泛 Amazon Web Services 服务影响的功能、凭证提供程序和其他功能。所有地方 SDKs 都有一系列地点（或来源），他们会检查这些地点（或来源），以便找到全局设置的值。以下是设置查找优先级的方法：

  1. 在代码中或服务客户端本身上设置的任何显式设置均优先于其他任何设置。

    • 有些设置可以根据每个操作进行设置，也可以根据需要针对调用的每个操作进行更改。对于 Amazon CLI 或 Amazon Tools for PowerShell，它们采用您在命令行上输入的每个操作参数的形式。对于 SDK，显式分配可以采用您在实例化 Amazon Web Services 服务 客户端或配置对象时或有时在调用单个 API 时设置的参数的形式。

  2. 仅限 Java/Kotlin：已选中该设置的 JVM 系统属性。如果已设置，则使用该值来配置客户端。

  3. 系统会检查环境变量。如果已设置，则使用该值来配置客户端。

  4. SDK 会检查共享credentials文件中的设置。如果已设置，则客户端将使用它。

  5. 设置的共享config文件。如果存在该设置，则 SDK 将使用该设置。

    • AWS_PROFILE环境变量或 aws.profile JVM 系统属性可用于指定 SDK 加载哪个配置文件。

  6. 最后使用 SDK 源代码本身提供的任何默认值。

注意

有些 SDKs 工具可能会按不同的顺序进行检查。此外，有些 SDKs 和工具还支持其他存储和检索参数的方法。例如， 适用于 .NET 的 Amazon SDK 支持名为 SDK Stor e 的其他来源。有关 SDK 或工具独有的提供者的更多信息，请参阅您正在使用的 SDK 或工具的特定指南。

顺序决定哪些方法优先使用并覆盖其他方法。例如，如果您在共享config文件中设置了配置文件，则只有在 SDK 或工具先检查其他位置之后，才能找到并使用该配置文件。这意味着，如果您在credentials文件中添加了设置，则会使用该设置而不是config文件中的设置。如果您使用设置和值配置环境变量，它将覆盖credentials和config文件中的该设置。最后，单个操作（Amazon CLI 命令行参数或 API 参数）或代码中的设置将覆盖该命令的所有其他值。

了解本指南的设置页面

本指南的 “设置” 参考部分中的页面详细介绍了可以通过各种机制进行设置的可用设置。下表列出了配置和凭证文件设置、环境变量以及（对于 Java 和 Kotlin SDKs）可以在代码之外用于配置该功能的 JVM 设置。每个列表中的每个链接主题都会将您带到相应的设置页面。

每个凭证提供商或功能都有一个页面，其中列出了用于配置该功能的设置。对于每种设置，您通常可以通过将设置添加到配置文件或通过设置环境变量来设置值，或者（仅适用于 Java 和 Kotlin）通过设置 JVM 系统属性来设置值。每个设置都列出了所有支持的在描述详细信息上方的方块中设置该值的方法。尽管优先级各不相同，但无论如何设置，生成的功能都是一样的。

描述中将包括默认值（如果有），如果您什么都不做，该值就会生效。它还定义了该设置的有效值。

例如，让我们来看看请求压缩功能页面中的一个设置。

disable_request_compression示例设置的信息记录了以下内容：

  • 有三种等效的方法可以控制代码库之外的请求压缩。您可以：

    • 使用在您的配置文件中进行设置 disable_request_compression

    • 使用将其设置为环境变量 AWS_DISABLE_REQUEST_COMPRESSION

    • 或者，如果你使用的是 Java 或 Kotlin SDK，请使用将其设置为 JVM 系统属性 aws.disableRequestCompression

    注意

    可能还有一种方法可以直接在代码中配置相同的功能，但本参考文献不涵盖这一点，因为它是每个 SDK 所独有的。如果您想在代码本身中设置配置，请参阅您的特定 SDK 指南或 API 参考。

  • 如果您什么都不做，则该值将默认为false。

  • 此布尔值设置的唯一有效值是true和false。

每个功能页面的底部都有一个 Support b y Amazon SDKs 和 tools 表。

此表显示您的 SDK 是否支持页面上列出的设置。该Supported列使用以下值表示支撑位：

  • Yes— 所写的 SDK 完全支持这些设置。

  • Partial— 支持某些设置或行为与描述有所不同。对于Partial，附加注释表示偏差。

  • No— 不支持任何设置。这并不能说明代码中是否可以实现相同的功能；它仅表示不支持列出的外部配置设置。

Config文件设置列表

下表中列出的设置可以在共享 Amazon config文件中分配。它们是全球性的，影响到所有人 Amazon Web Services 服务。 SDKs 而且工具还可能支持独特的设置和环境变量。要查看仅单个 SDK 或工具支持的设置和环境变量，请参阅特定的 SDK 或工具指南。

设置名称 详细信息
account_id_endpoint_mode 基于账户的终端节点
api_versions 常规配置设置
aws_access_key_id Amazon 访问密钥
aws_account_id 基于账户的终端节点
aws_secret_access_key Amazon 访问密钥
aws_session_token Amazon 访问密钥
ca_bundle 常规配置设置
credential_process 进程凭证提供者
credential_source 代入角色凭证提供者
defaults_mode 智能配置默认值
disable_host_prefix_injection 主机前缀注入
disable_request_compression 请求压缩
duration_seconds 代入角色凭证提供者
ec2_metadata_service_endpoint IMDS 凭证提供者
ec2_metadata_service_endpoint_mode IMDS 凭证提供者
ec2_metadata_v1_disabled IMDS 凭证提供者
endpoint_discovery_enabled 端点发现
endpoint_url 特定于服务的端点
external_id 代入角色凭证提供者
ignore_configured_endpoint_urls 特定于服务的端点
max_attempts 重试行为
metadata_service_num_attempts Amazon EC2 实例元数据
metadata_service_timeout Amazon EC2 实例元数据
mfa_serial 代入角色凭证提供者
output 常规配置设置
parameter_validation 常规配置设置
region Amazon Web Services 区域
request_checksum_calculation Amazon S3 的数据完整性保护
request_min_compression_size_bytes 请求压缩
response_checksum_validation Amazon S3 的数据完整性保护
retry_mode 重试行为
role_arn 代入角色凭证提供者
role_session_name 代入角色凭证提供者
s3_disable_multiregion_access_points Amazon S3 多区域访问点
s3_use_arn_region Amazon S3 接入点
sdk_ua_app_id 应用程序 ID
source_profile 代入角色凭证提供者
sso_account_id IAM Identity Center 凭证提供者
sso_region IAM Identity Center 凭证提供者
sso_registration_scopes IAM Identity Center 凭证提供者
sso_role_name IAM Identity Center 凭证提供者
sso_start_url IAM Identity Center 凭证提供者
sts_regional_endpoints Amazon STS 区域端点
use_dualstack_endpoint 双堆栈和 FIPS 端点
use_fips_endpoint 双堆栈和 FIPS 端点
web_identity_token_file 代入角色凭证提供者

Credentials文件设置列表

下表中列出的设置可以在共享 Amazon credentials文件中分配。它们是全球性的，影响到所有人 Amazon Web Services 服务。 SDKs 而且工具还可能支持独特的设置和环境变量。要查看仅单个 SDK 或工具支持的设置和环境变量，请参阅特定的 SDK 或工具指南。

设置名称 详细信息
aws_access_key_id Amazon 访问密钥
aws_secret_access_key Amazon 访问密钥
aws_session_token Amazon 访问密钥

环境变量列表

下表列出了 SDKs 大多数人支持的环境变量。它们是全球性的，影响到所有人 Amazon Web Services 服务。 SDKs 而且工具还可能支持独特的设置和环境变量。要查看仅单个 SDK 或工具支持的设置和环境变量，请参阅特定的 SDK 或工具指南。

设置名称 详细信息
AWS_ACCESS_KEY_ID Amazon 访问密钥
AWS_ACCOUNT_ID 基于账户的终端节点
AWS_ACCOUNT_ID_ENDPOINT_MODE 基于账户的终端节点
AWS_CA_BUNDLE 常规配置设置
AWS_CONFIG_FILE 查找和更改共享credentials文件configAmazon SDKs 和工具的位置
AWS_CONTAINER_AUTHORIZATION_TOKEN 容器凭证提供者
AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE 容器凭证提供者
AWS_CONTAINER_CREDENTIALS_FULL_URI 容器凭证提供者
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI 容器凭证提供者
AWS_DEFAULTS_MODE 智能配置默认值
AWS_DISABLE_HOST_PREFIX_INJECTION 主机前缀注入
AWS_DISABLE_REQUEST_COMPRESSION 请求压缩
AWS_EC2_METADATA_DISABLED IMDS 凭证提供者
AWS_EC2_METADATA_SERVICE_ENDPOINT IMDS 凭证提供者
AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE IMDS 凭证提供者
AWS_EC2_METADATA_V1_DISABLED IMDS 凭证提供者
AWS_ENABLE_ENDPOINT_DISCOVERY 端点发现
AWS_ENDPOINT_URL 特定于服务的端点
AWS_ENDPOINT_URL_<SERVICE> 特定于服务的端点
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS 特定于服务的端点
AWS_MAX_ATTEMPTS 重试行为
AWS_METADATA_SERVICE_NUM_ATTEMPTS Amazon EC2 实例元数据
AWS_METADATA_SERVICE_TIMEOUT Amazon EC2 实例元数据
AWS_PROFILE 使用共享config和credentials文件进行全局配置 Amazon SDKs 和工具
AWS_REGION Amazon Web Services 区域
AWS_REQUEST_CHECKSUM_CALCULATION Amazon S3 的数据完整性保护
AWS_REQUEST_MIN_COMPRESSION_SIZE_BYTES 请求压缩
AWS_RESPONSE_CHECKSUM_VALIDATION Amazon S3 的数据完整性保护
AWS_RETRY_MODE 重试行为
AWS_ROLE_ARN 代入角色凭证提供者
AWS_ROLE_SESSION_NAME 代入角色凭证提供者
AWS_S3_DISABLE_MULTIREGION_ACCESS_POINTS Amazon S3 多区域访问点
AWS_S3_USE_ARN_REGION Amazon S3 接入点
AWS_SDK_UA_APP_ID 应用程序 ID
AWS_SECRET_ACCESS_KEY Amazon 访问密钥
AWS_SESSION_TOKEN Amazon 访问密钥
AWS_SHARED_CREDENTIALS_FILE 查找和更改共享credentials文件configAmazon SDKs 和工具的位置
AWS_STS_REGIONAL_ENDPOINTS Amazon STS 区域端点
AWS_USE_DUALSTACK_ENDPOINT 双堆栈和 FIPS 端点
AWS_USE_FIPS_ENDPOINT 双堆栈和 FIPS 端点
AWS_WEB_IDENTITY_TOKEN_FILE 代入角色凭证提供者

JVM 系统属性列表

您可以将以下 JVM 系统属性用于 适用于 Java 的 Amazon SDK 和 适用于 Kotlin 的 Amazon SDK （以 JVM 为目标）。有关如何设置 JVM 系统属性的说明，请参阅如何设置 JVM 系统属性。

设置名称 详细信息
aws.accessKeyId Amazon 访问密钥
aws.accountId 基于账户的终端节点
aws.accountIdEndpointMode 基于账户的终端节点
aws.configFile 查找和更改共享credentials文件configAmazon SDKs 和工具的位置
aws.defaultsMode 智能配置默认值
aws.disableEc2MetadataV1 IMDS 凭证提供者
aws.disableHostPrefixInjection 主机前缀注入
aws.disableRequestCompression 请求压缩
aws.ec2MetadataServiceEndpoint IMDS 凭证提供者
aws.ec2MetadataServiceEndpointMode IMDS 凭证提供者
aws.endpointDiscoveryEnabled 端点发现
aws.endpointUrl 特定于服务的端点
aws.endpointUrl<ServiceName> 特定于服务的端点
aws.ignoreConfiguredEndpointUrls 特定于服务的端点
aws.maxAttempts 重试行为
aws.profile 使用共享config和credentials文件进行全局配置 Amazon SDKs 和工具
aws.region Amazon Web Services 区域
aws.requestChecksumCalculation Amazon S3 的数据完整性保护
aws.requestMinCompressionSizeBytes 请求压缩
aws.responseChecksumValidation Amazon S3 的数据完整性保护
aws.retryMode 重试行为
aws.roleArn 代入角色凭证提供者
aws.roleSessionName 代入角色凭证提供者
aws.s3DisableMultiRegionAccessPoints Amazon S3 多区域访问点
aws.s3UseArnRegion Amazon S3 接入点
aws.secretAccessKey Amazon 访问密钥
aws.sessionToken Amazon 访问密钥
aws.sharedCredentialsFile 查找和更改共享credentials文件configAmazon SDKs 和工具的位置
aws.useDualstackEndpoint 双堆栈和 FIPS 端点
aws.useFipsEndpoint 双堆栈和 FIPS 端点
aws.userAgentAppId 应用程序 ID
aws.webIdentityTokenFile 代入角色凭证提供者