AWS SDK 和工具设置参考 - AWS SDK 和工具
创建服务客户端设置的优先级了解本指南的设置页面Config文件设置列表Credentials文件设置列表环境变量列表JVM 系统属性列表

AWS SDK 和工具设置参考

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

以下章节介绍了有关配置设置的详细信息：

创建服务客户端

要以编程方式访问 AWS 服务，SDK 使用每个 AWS 服务 的客户端类/对象。例如，如果您的应用程序需要访问 Amazon EC2，则您的应用程序会创建一个 Amazon EC2 客户端对象来与该服务交互。然后，您可以使用服务客户端向该 AWS 服务 发出请求。在大多数 SDK 中，服务客户端对象是不可变的，因此您必须为向其发出请求的每个服务创建一个新的客户端，并使用不同的配置向同一服务发出请求。

设置的优先级

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

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

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

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

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

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

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

    • 可以使用 AWS_PROFILE 环境变量或 aws.profile JVM 系统属性来指定 SDK 要加载的配置文件。

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

注意

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

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

了解本指南的设置页面

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

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

描述中将包括默认值（如果有），如果您不执行任何操作，系统将会使用该值。描述中还定义了该设置的有效值。

例如，下面是 请求压缩 功能页面的设置示例。

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

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

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

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

    • 如果您使用的是 Java 或 Kotlin SDK，则还可以使用 aws.disableRequestCompression 将其设置为 JVM 系统属性

    注意

    可能还有一种方法可以直接在代码中配置相同的功能，但由于这种方法因 SDK 而异，因此本参考未作介绍。如果需要在代码中直接设置配置，请参阅具体的 SDK 指南或 API 参考。

  • 如果您不执行任何操作，则该值将默认为 false。

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

每个功能页面的底部都有一个 AWS SDK 和工具支持表。

该表会显示您的 SDK 是否支持该页面上列出的设置。Supported 列指示支持级别，具有下列值：

  • Yes：该 SDK 完全支持描述的设置。

  • Partial：支持部分设置，或者行为与描述有所不同。对于 Partial，会用一条附加注释来说明偏差。

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

Config文件设置列表

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

设置名称 详细信息
account_id_endpoint_mode 基于账户的端点
api_versions 常规配置设置
auth_scheme_preference 身份验证方案
aws_access_key_id AWS 访问密钥
aws_account_id 基于账户的端点
aws_secret_access_key AWS 访问密钥
aws_session_token AWS 访问密钥
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 AWS 区域
request_checksum_calculation Amazon S3 数据完整性保护
request_min_compression_size_bytes 请求压缩
response_checksum_validation Amazon S3 数据完整性保护
retry_mode 重试行为
role_arn 代入角色凭证提供者
role_session_name 代入角色凭证提供者
s3_disable_express_session_auth S3 Express One Zone 会话身份验证
s3_disable_multiregion_access_points Amazon S3 多区域访问点
s3_use_arn_region Amazon S3 接入点
sdk_ua_app_id 应用程序 ID
sigv4a_signing_region_set 身份验证方案
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 AWS STS 区域性端点
use_dualstack_endpoint 双堆栈和 FIPS 端点
use_fips_endpoint 双堆栈和 FIPS 端点
web_identity_token_file 代入角色凭证提供者

Credentials文件设置列表

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

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

环境变量列表

下表列出了大多数 SDK 都支持的环境变量。它们是全局性的，影响到所有 AWS 服务。SDK 和工具还可能支持独有的设置和环境变量。要查看仅受单个 SDK 或工具支持的设置和环境变量，请参阅具体的 SDK 或工具指南。

设置名称 详细信息
AWS_ACCESS_KEY_ID AWS 访问密钥
AWS_ACCOUNT_ID 基于账户的端点
AWS_ACCOUNT_ID_ENDPOINT_MODE 基于账户的端点
AWS_AUTH_SCHEME_PREFERENCE 身份验证方案
AWS_CA_BUNDLE 常规配置设置
AWS_CONFIG_FILE 查找和更改 AWS SDK 和工具的共享 config 和 credentials 文件的位置
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 文件进行 AWS SDK 和工具全局配置
AWS_REGION AWS 区域
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_EXPRESS_SESSION_AUTH S3 Express One Zone 会话身份验证
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 AWS 访问密钥
AWS_SESSION_TOKEN AWS 访问密钥
AWS_SHARED_CREDENTIALS_FILE 查找和更改 AWS SDK 和工具的共享 config 和 credentials 文件的位置
AWS_SIGV4A_SIGNING_REGION_SET 身份验证方案
AWS_STS_REGIONAL_ENDPOINTS AWS STS 区域性端点
AWS_USE_DUALSTACK_ENDPOINT 双堆栈和 FIPS 端点
AWS_USE_FIPS_ENDPOINT 双堆栈和 FIPS 端点
AWS_WEB_IDENTITY_TOKEN_FILE 代入角色凭证提供者

JVM 系统属性列表

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

设置名称 详细信息
aws.accessKeyId AWS 访问密钥
aws.accountId 基于账户的端点
aws.accountIdEndpointMode 基于账户的端点
aws.authSchemePreference 身份验证方案
aws.configFile 查找和更改 AWS SDK 和工具的共享 config 和 credentials 文件的位置
aws.defaultsMode 智能配置默认值
aws.disableEc2MetadataV1 IMDS 凭证提供者
aws.disableHostPrefixInjection 主机前缀注入
aws.disableRequestCompression 请求压缩
aws.disableS3ExpressAuth S3 Express One Zone 会话身份验证
aws.ec2MetadataServiceEndpoint IMDS 凭证提供者
aws.ec2MetadataServiceEndpointMode IMDS 凭证提供者
aws.endpointDiscoveryEnabled 端点发现
aws.endpointUrl 特定于服务的端点
aws.endpointUrl<ServiceName> 特定于服务的端点
aws.ignoreConfiguredEndpointUrls 特定于服务的端点
aws.maxAttempts 重试行为
aws.profile 使用共享的 config 和 credentials 文件进行 AWS SDK 和工具全局配置
aws.region AWS 区域
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 AWS 访问密钥
aws.sessionToken AWS 访问密钥
aws.sharedCredentialsFile 查找和更改 AWS SDK 和工具的共享 config 和 credentials 文件的位置
aws.useDualstackEndpoint 双堆栈和 FIPS 端点
aws.useFipsEndpoint 双堆栈和 FIPS 端点
aws.webIdentityTokenFile 代入角色凭证提供者
sdk.ua.appId 应用程序 ID