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

# Amazon SDKs 和工具设置参考
<a name="settings-reference"></a>

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

以下章节介绍了有关配置设置的详细信息：
+ [Amazon SDKs 和 Tools 标准化凭证提供商](standardized-credentials.md)— 通用凭证提供商在多个 SDKs证书提供者之间实现标准化。
+ [Amazon SDKs 和 “工具” 标准化功能](standardized-features.md)— 通用功能跨多个标准化 SDKs。

## 创建服务客户端
<a name="creatingServiceClients"></a>

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

## 设置的优先级
<a name="precedenceOfSettings"></a>

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

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

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

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

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

1. 检查共享的 `config` 文件来查找该设置。如果存在该设置，则 SDK 将使用该设置。
   + 可以使用 `AWS_PROFILE` 环境变量或 `aws.profile` JVM 系统属性来指定 SDK 要加载的配置文件。

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

**注意**  
有些 SDKs 工具可能会按不同的顺序进行检查。此外，有些 SDKs 和工具还支持其他存储和检索参数的方法。例如， 适用于 .NET 的 Amazon SDK 支持名为 [SDK 商店](https://docs.amazonaws.cn/sdk-for-net/latest/developer-guide/sdk-store.html)的其他来源。有关 SDK 或工具独有的提供者的更多信息，请参阅您正在使用的 SDK 或工具的特定指南。

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

## 了解本指南的设置页面
<a name="settingsPages"></a>

本指南中**设置参考**部分的相关页面详细介绍了可以通过各种机制设定的可用设置。下表列出了配置和凭证文件设置、环境变量以及（对于 Java 和 Kotlin SDKs）可以在代码之外用于配置该功能的 JVM 设置。每个列表中链接的每个主题都会指向相应的设置页面。
+ [`Config`文件设置列表](#ConfigFileSettings)
+ [`Credentials`文件设置列表](#CredFileSettings)
+ [环境变量列表](#EVarSettings)
+ [JVM 系统属性列表](#JVMSettings)



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

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

 例如，下面是 [请求压缩](feature-compression.md) 功能页面的设置示例。

`disable_request_compression` 示例设置的信息记录了以下内容：
+ 有三种等效的方法可以用来在代码库之外控制请求压缩。您可以：
  + 使用 `disable_request_compression` 在配置文件中进行设置 
  +  使用 `AWS_DISABLE_REQUEST_COMPRESSION` 将其设置为环境变量
  + 如果您使用的是 Java 或 Kotlin SDK，则还可以使用 `aws.disableRequestCompression` 将其设置为 JVM 系统属性
**注意**  
可能还有一种方法可以直接在代码中配置相同的功能，但由于这种方法因 SDK 而异，因此本参考未作介绍。如果需要在代码中直接设置配置，请参阅具体的 SDK 指南或 API 参考。
+ 如果您不执行任何操作，则该值将默认为 `false`。
+ 此布尔值设置的唯一有效值是 `true` 和 `false`。

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

该表会显示您的 SDK 是否支持该页面上列出的设置。`Supported` 列指示支持级别，具有下列值：
+ `Yes`：该 SDK 完全支持描述的设置。
+ `Partial`：支持部分设置，或者行为与描述有所不同。对于 `Partial`，会用一条附加注释来说明偏差。
+ `No`：不支持任何设置。这并不能说明代码中是否可以实现相同的功能；仅指示不支持列出的外部配置设置。

## `Config`文件设置列表
<a name="ConfigFileSettings"></a>

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


| 设置名称 | Details | 
| --- | --- | 
|  account\$1id\$1endpoint\$1mode  | [基于账户的终端节点](feature-account-endpoints.md)  | 
|  api\$1versions  | [常规配置设置](feature-gen-config.md)  | 
|  auth\$1scheme\$1preference  | [身份验证方案](feature-auth-scheme.md)  | 
|  aws\$1access\$1key\$1id  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws\$1account\$1id  | [基于账户的终端节点](feature-account-endpoints.md)  | 
|  aws\$1secret\$1access\$1key  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws\$1session\$1token  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  ca\$1bundle  | [常规配置设置](feature-gen-config.md)  | 
|  credential\$1process  | [进程凭证提供者](feature-process-credentials.md)  | 
|  credential\$1source  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  defaults\$1mode  | [智能配置默认值](feature-smart-config-defaults.md)  | 
|  disable\$1host\$1prefix\$1injection  | [主机前缀注入](feature-host-prefix.md)  | 
|  disable\$1request\$1compression  | [请求压缩](feature-compression.md)  | 
|  duration\$1seconds  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  ec2\$1metadata\$1service\$1endpoint  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  ec2\$1metadata\$1service\$1endpoint\$1mode  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  ec2\$1metadata\$1v1\$1disabled  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  endpoint\$1discovery\$1enabled  | [端点发现](feature-endpoint-discovery.md)  | 
|  endpoint\$1url  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  external\$1id  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  ignore\$1configured\$1endpoint\$1urls  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  max\$1attempts  | [重试行为](feature-retry-behavior.md)  | 
|  metadata\$1service\$1num\$1attempts  | [Amazon EC2 实例元数据](feature-ec2-instance-metadata.md)  | 
|  metadata\$1service\$1timeout  | [Amazon EC2 实例元数据](feature-ec2-instance-metadata.md)  | 
|  mfa\$1serial  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  output  | [常规配置设置](feature-gen-config.md)  | 
|  parameter\$1validation  | [常规配置设置](feature-gen-config.md)  | 
|  region  | [Amazon Web Services 区域](feature-region.md)  | 
|  request\$1checksum\$1calculation  | [Amazon S3 数据完整性保护](feature-dataintegrity.md)  | 
|  request\$1min\$1compression\$1size\$1bytes  | [请求压缩](feature-compression.md)  | 
|  response\$1checksum\$1validation  | [Amazon S3 数据完整性保护](feature-dataintegrity.md)  | 
|  retry\$1mode  | [重试行为](feature-retry-behavior.md)  | 
|  role\$1arn  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  role\$1session\$1name  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  s3\$1disable\$1express\$1session\$1auth  | [S3 Express One Zone 会话身份验证](feature-s3-express.md)  | 
|  s3\$1disable\$1multiregion\$1access\$1points  | [Amazon S3 多区域访问点](feature-s3-mrap.md)  | 
|  s3\$1use\$1arn\$1region  | [Amazon S3 接入点](feature-s3-access-point.md)  | 
|  sdk\$1ua\$1app\$1id  | [应用程序 ID](feature-appid.md)  | 
|  sigv4a\$1signing\$1region\$1set  | [身份验证方案](feature-auth-scheme.md)  | 
|  source\$1profile  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  sso\$1account\$1id  | [IAM Identity Center 凭证提供者](feature-sso-credentials.md)  | 
|  sso\$1region  | [IAM Identity Center 凭证提供者](feature-sso-credentials.md)  | 
|  sso\$1registration\$1scopes  | [IAM Identity Center 凭证提供者](feature-sso-credentials.md)  | 
|  sso\$1role\$1name  | [IAM Identity Center 凭证提供者](feature-sso-credentials.md)  | 
|  sso\$1start\$1url  | [IAM Identity Center 凭证提供者](feature-sso-credentials.md)  | 
|  sts\$1regional\$1endpoints  | [Amazon STS 区域端点](feature-sts-regionalized-endpoints.md)  | 
|  use\$1dualstack\$1endpoint  | [双堆栈和 FIPS 端点](feature-endpoints.md)  | 
|  use\$1fips\$1endpoint  | [双堆栈和 FIPS 端点](feature-endpoints.md)  | 
|  web\$1identity\$1token\$1file  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 

## `Credentials`文件设置列表
<a name="CredFileSettings"></a>

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


| 设置名称 | Details | 
| --- | --- | 
|  aws\$1access\$1key\$1id  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws\$1secret\$1access\$1key  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws\$1session\$1token  | [Amazon 访问密钥](feature-static-credentials.md)  | 

## 环境变量列表
<a name="EVarSettings"></a>

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


| 设置名称 | Details | 
| --- | --- | 
|  AWS\$1ACCESS\$1KEY\$1ID  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  AWS\$1ACCOUNT\$1ID  | [基于账户的终端节点](feature-account-endpoints.md)  | 
|  AWS\$1ACCOUNT\$1ID\$1ENDPOINT\$1MODE  | [基于账户的终端节点](feature-account-endpoints.md)  | 
|  AWS\$1AUTH\$1SCHEME\$1PREFERENCE  | [身份验证方案](feature-auth-scheme.md)  | 
|  AWS\$1CA\$1BUNDLE  | [常规配置设置](feature-gen-config.md)  | 
|  AWS\$1CONFIG\$1FILE  | [查找和更改共享`credentials`文件`config`Amazon SDKs 和工具的位置](file-location.md)  | 
|  AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN  | [容器凭证提供者](feature-container-credentials.md)  | 
|  AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN\$1FILE  | [容器凭证提供者](feature-container-credentials.md)  | 
|  AWS\$1CONTAINER\$1CREDENTIALS\$1FULL\$1URI  | [容器凭证提供者](feature-container-credentials.md)  | 
|  AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI  | [容器凭证提供者](feature-container-credentials.md)  | 
|  AWS\$1DEFAULTS\$1MODE  | [智能配置默认值](feature-smart-config-defaults.md)  | 
|  AWS\$1DISABLE\$1HOST\$1PREFIX\$1INJECTION  | [主机前缀注入](feature-host-prefix.md)  | 
|  AWS\$1DISABLE\$1REQUEST\$1COMPRESSION  | [请求压缩](feature-compression.md)  | 
|  AWS\$1EC2\$1METADATA\$1DISABLED  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  AWS\$1EC2\$1METADATA\$1SERVICE\$1ENDPOINT\$1MODE  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  AWS\$1EC2\$1METADATA\$1V1\$1DISABLED  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  AWS\$1ENABLE\$1ENDPOINT\$1DISCOVERY  | [端点发现](feature-endpoint-discovery.md)  | 
|  AWS\$1ENDPOINT\$1URL  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  AWS\$1ENDPOINT\$1URL\$1<SERVICE>  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  AWS\$1IGNORE\$1CONFIGURED\$1ENDPOINT\$1URLS  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  AWS\$1MAX\$1ATTEMPTS  | [重试行为](feature-retry-behavior.md)  | 
|  AWS\$1METADATA\$1SERVICE\$1NUM\$1ATTEMPTS  | [Amazon EC2 实例元数据](feature-ec2-instance-metadata.md)  | 
|  AWS\$1METADATA\$1SERVICE\$1TIMEOUT  | [Amazon EC2 实例元数据](feature-ec2-instance-metadata.md)  | 
|  AWS\$1PROFILE  | [使用共享`config`和`credentials`文件进行全局配置 Amazon SDKs 和工具](file-format.md)  | 
|  AWS\$1REGION  | [Amazon Web Services 区域](feature-region.md)  | 
|  AWS\$1REQUEST\$1CHECKSUM\$1CALCULATION  | [Amazon S3 数据完整性保护](feature-dataintegrity.md)  | 
|  AWS\$1REQUEST\$1MIN\$1COMPRESSION\$1SIZE\$1BYTES  | [请求压缩](feature-compression.md)  | 
|  AWS\$1RESPONSE\$1CHECKSUM\$1VALIDATION  | [Amazon S3 数据完整性保护](feature-dataintegrity.md)  | 
|  AWS\$1RETRY\$1MODE  | [重试行为](feature-retry-behavior.md)  | 
|  AWS\$1ROLE\$1ARN  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  AWS\$1ROLE\$1SESSION\$1NAME  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  AWS\$1S3\$1DISABLE\$1EXPRESS\$1SESSION\$1AUTH  | [S3 Express One Zone 会话身份验证](feature-s3-express.md)  | 
|  AWS\$1S3\$1DISABLE\$1MULTIREGION\$1ACCESS\$1POINTS  | [Amazon S3 多区域访问点](feature-s3-mrap.md)  | 
|  AWS\$1S3\$1USE\$1ARN\$1REGION  | [Amazon S3 接入点](feature-s3-access-point.md)  | 
|  AWS\$1SDK\$1UA\$1APP\$1ID  | [应用程序 ID](feature-appid.md)  | 
|  AWS\$1SECRET\$1ACCESS\$1KEY  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  AWS\$1SESSION\$1TOKEN  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  AWS\$1SHARED\$1CREDENTIALS\$1FILE  | [查找和更改共享`credentials`文件`config`Amazon SDKs 和工具的位置](file-location.md)  | 
|  AWS\$1SIGV4A\$1SIGNING\$1REGION\$1SET  | [身份验证方案](feature-auth-scheme.md)  | 
|  AWS\$1STS\$1REGIONAL\$1ENDPOINTS  | [Amazon STS 区域端点](feature-sts-regionalized-endpoints.md)  | 
|  AWS\$1USE\$1DUALSTACK\$1ENDPOINT  | [双堆栈和 FIPS 端点](feature-endpoints.md)  | 
|  AWS\$1USE\$1FIPS\$1ENDPOINT  | [双堆栈和 FIPS 端点](feature-endpoints.md)  | 
|  AWS\$1WEB\$1IDENTITY\$1TOKEN\$1FILE  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 

## JVM 系统属性列表
<a name="JVMSettings"></a>

您可以将以下 JVM 系统属性用于 适用于 Java 的 Amazon SDK 和 适用于 Kotlin 的 Amazon SDK （以 JVM 为目标）。有关如何设置 JVM 系统属性的说明，请参阅[如何设置 JVM 系统属性](jvm-system-properties.md#jvm-sys-props-set)。


| 设置名称 | Details | 
| --- | --- | 
|  aws.accessKeyId  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws.accountId  | [基于账户的终端节点](feature-account-endpoints.md)  | 
|  aws.accountIdEndpointMode  | [基于账户的终端节点](feature-account-endpoints.md)  | 
|  aws.authSchemePreference  | [身份验证方案](feature-auth-scheme.md)  | 
|  aws.configFile  | [查找和更改共享`credentials`文件`config`Amazon SDKs 和工具的位置](file-location.md)  | 
|  aws.defaultsMode  | [智能配置默认值](feature-smart-config-defaults.md)  | 
|  aws.disableEc2MetadataV1  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  aws.disableHostPrefixInjection  | [主机前缀注入](feature-host-prefix.md)  | 
|  aws.disableRequestCompression  | [请求压缩](feature-compression.md)  | 
|  aws.disableS3ExpressAuth  | [S3 Express One Zone 会话身份验证](feature-s3-express.md)  | 
|  aws.ec2MetadataServiceEndpoint  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  aws.ec2MetadataServiceEndpointMode  | [IMDS 凭证提供者](feature-imds-credentials.md)  | 
|  aws.endpointDiscoveryEnabled  | [端点发现](feature-endpoint-discovery.md)  | 
|  aws.endpointUrl  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  aws.endpointUrl<ServiceName>  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  aws.ignoreConfiguredEndpointUrls  | [特定于服务的端点](feature-ss-endpoints.md)  | 
|  aws.maxAttempts  | [重试行为](feature-retry-behavior.md)  | 
|  aws.profile  | [使用共享`config`和`credentials`文件进行全局配置 Amazon SDKs 和工具](file-format.md)  | 
|  aws.region  | [Amazon Web Services 区域](feature-region.md)  | 
|  aws.requestChecksumCalculation  | [Amazon S3 数据完整性保护](feature-dataintegrity.md)  | 
|  aws.requestMinCompressionSizeBytes  | [请求压缩](feature-compression.md)  | 
|  aws.responseChecksumValidation  | [Amazon S3 数据完整性保护](feature-dataintegrity.md)  | 
|  aws.retryMode  | [重试行为](feature-retry-behavior.md)  | 
|  aws.roleArn  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  aws.roleSessionName  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  aws.s3DisableMultiRegionAccessPoints  | [Amazon S3 多区域访问点](feature-s3-mrap.md)  | 
|  aws.s3UseArnRegion  | [Amazon S3 接入点](feature-s3-access-point.md)  | 
|  aws.secretAccessKey  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws.sessionToken  | [Amazon 访问密钥](feature-static-credentials.md)  | 
|  aws.sharedCredentialsFile  | [查找和更改共享`credentials`文件`config`Amazon SDKs 和工具的位置](file-location.md)  | 
|  aws.useDualstackEndpoint  | [双堆栈和 FIPS 端点](feature-endpoints.md)  | 
|  aws.useFipsEndpoint  | [双堆栈和 FIPS 端点](feature-endpoints.md)  | 
|  aws.webIdentityTokenFile  | [代入角色凭证提供者](feature-assume-role-credentials.md)  | 
|  sdk.ua.appId  | [应用程序 ID](feature-appid.md)  |