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

# 在代码中配置适用于 C\$1\$1 的 AWS SDK 服务客户端
<a name="client-config"></a>

当直接在代码中处理配置时，配置范围仅限于使用该代码的应用程序。在该应用程序中，您可选择以下配置方式：对所有服务客户端的全局配置、对某一特定 AWS 服务类型所有客户端的配置，或对某个具体服务客户端实例的配置。

适用于 C\$1\$1 的 AWS SDK 包含 AWS 服务客户端类，这些类提供了与您应用程序中使用的 AWS 服务进行交互的功能。在适用于 C\$1\$1 的 SDK 中，您可以更改默认客户端配置，这在您想要执行以下操作时非常有用：
+ 通过代理连接到 Internet
+ 更改 HTTP 传输设置，例如连接超时和请求重试次数
+ 指定 TCP 套接字缓冲区大小提示

`ClientConfiguration` 是适用于 C\$1\$1 的 SDK 中的一个结构，您可以在代码中将其实例化并加以使用。以下代码段说明了如何使用该类通过代理访问 Amazon S3。

```
Aws::Client::ClientConfiguration clientConfig;
clientConfig.proxyHost = "localhost";
clientConfig.proxyPort = 1234;
clientConfig.proxyScheme = Aws::Http::Scheme::HTTPS;
Aws::S3::S3Client(clientConfig);
```

## 配置变量声明
<a name="config-vars-declarations"></a>

 `ClientConfiguration` 结构声明了以下成员变量：

```
Aws::String accountId;
Aws::String accountIdEndpointMode = "preferred";
bool allowSystemProxy = false;
Aws::String appId;
Aws::String caPath;
Aws::String caFile;

struct {
  RequestChecksumCalculation requestChecksumCalculation = RequestChecksumCalculation::WHEN_SUPPORTED;
  ResponseChecksumValidation responseChecksumValidation = ResponseChecksumValidation::WHEN_SUPPORTED;
} checksumConfig;

ProviderFactories configFactories = ProviderFactories::defaultFactories;
long connectTimeoutMs = 1000;

struct CredentialProviderConfiguration {
    Aws::String profile;
    Aws::String region;
    struct {
        long metadataServiceNumAttempts = 1;
        long metadataServiceTimeout = 1;
        std::shared_ptr<RetryStrategy> imdsRetryStrategy;
        bool disableImdsV1;
        bool disableImds;
    } imdsConfig;
    struct STSCredentialsCredentialProviderConfiguration {
        Aws::String roleArn;
        Aws::String sessionName;
        Aws::String tokenFilePath;
        std::chrono::milliseconds retrieveCredentialsFutureTimeout = std::chrono::seconds(10);
    } stsCredentialsProviderConfig;
} credentialProviderConfig;

bool disableExpectHeader = false;
bool disableIMDS = false;
bool disableImdsV1 = false;
bool enableClockSkewAdjustment = true;
Aws::Crt::Optional<bool> enableEndpointDiscovery;
bool enableHostPrefixInjection = true;
bool enableHttpClientTrace = false;
bool enableTcpKeepAlive = true;
Aws::String endpointOverride;
std::shared_ptr<Aws::Utils::Threading::Executor> executor = nullptr;
FollowRedirectsPolicy followRedirects;
Aws::Http::TransferLibType httpLibOverride;
Aws::Http::TransferLibPerformanceMode httpLibPerfMode = Http::TransferLibPerformanceMode::LOW_LATENCY;
long httpRequestTimeoutMs = 0;
unsigned long lowSpeedLimit = 1;
unsigned maxConnections = 25;
Aws::Utils::Array<Aws::String> nonProxyHosts;
Aws::String profileName;
Aws::String proxyCaFile;
Aws::String proxyCaPath;
Aws::Http::Scheme proxyScheme;
Aws::String proxyHost;
unsigned proxyPort = 0;
Aws::String proxyUserName;
Aws::String proxyPassword;
Aws::String proxySSLCertPath;
Aws::String proxySSLCertType;
Aws::String proxySSLKeyPath;
Aws::String proxySSLKeyType;
Aws::String proxySSLKeyPassword;
std::shared_ptr<Aws::Utils::RateLimits::RateLimiterInterface> readRateLimiter = nullptr;
Aws::String region;
Aws::Client::RequestCompressionConfig requestCompressionConfig;
long requestTimeoutMs = 0;
std::shared_ptr<RetryStrategy> retryStrategy = nullptr;
Aws::Http::Scheme scheme;
unsigned long tcpKeepAliveIntervalMs = 30000;
std::shared_ptr<smithy::components::tracing::TelemetryProvider> telemetryProvider;
Aws::String userAgent;
bool useDualStack = false;
bool useFIPS = false;
bool verifySSL = true;
Aws::Http::Version version = Http::Version::HTTP_VERSION_2TLS;

struct WinHTTPOptions {
  bool useAnonymousAuth = false;
} winHTTPOptions;

std::shared_ptr<Aws::Utils::RateLimits::RateLimiterInterface> writeRateLimiter = nullptr;

static Aws::String LoadConfigFromEnvOrProfile(const Aws::String& envKey, const Aws::String& profile,
                                              const Aws::String& profileProperty, const Aws::Vector<Aws::String>& allowedValues,
                                              const Aws::String& defaultValue);
```

## 配置变量描述
<a name="configuration-variables"></a>

以下列表介绍了可用于自定义客户端行为的 `ClientConfiguration` 成员变量。

**accountId**  
指定 AWS 账户 ID 以用于基于账户的端点路由。使用格式 111122223333。基于账户的端点路由可提高某些服务的请求性能。

**accountIdEndpointMode**  
控制基于账户的端点路由行为。有效值为“required”、“disabled”或“preferred”。默认值为“preferred”。设置为“disabled”可在必要时关闭基于账户的端点路由。

**allowSystemProxy**  
控制 HTTP 客户端是否发现系统代理服务器设置。默认设置为 false。设置为 true 以启用自动代理发现。

**appId**  
指定可选的特定于应用程序的标识符。设置后，此值将以 `App/{appId}` 格式附加到 `User-Agent` 标头中。您可以使用 `AWS_SDK_UA_APP_ID` 环境变量或 `sdk_ua_app_id` 共享配置文件属性设置此值。

**caPath、caFile**  
指示 HTTP 客户端查找 SSL 证书信任存储的位置。示例信任存储库可能是使用 OpenSSL `c_rehash` 实用程序准备的目录。除非您的环境使用符号链接，否则无需设置这些变量。这些变量对 Windows 和 macOS 系统没有影响。

**checksumConfig**  
包含校验和计算和验证设置。包括 `requestChecksumCalculation` 和 `responseChecksumValidation`，默认值为 WHEN\$1SUPPORTED。

**configFactories**  
指定用于初始化客户端实用程序类的工厂方法，例如 `Executor` 和 `RetryStrategy`。除非被覆盖，否则使用默认工厂。

**requestTimeoutMs 和 connectTimeoutMs**  
指定 HTTP 请求超时前的等待时间（以毫秒为单位）。例如，在传输大文件时，可以考虑增加这些时间。

**credentialProviderConfig**  
包含凭证提供程序的配置设置。使用此结构来自定义 SDK 获取 AWS 凭证的方式。

**disableExpectHeader**  
仅适用于 CURL HTTP 客户端。默认情况下，CURL 会在 HTTP 请求中添加“Expect: 100-Continue”标头，以避免在服务器收到标头后立即返回错误的情况下发送 HTTP 有效载荷。此行为可以节省一次网络往返，在有效载荷较小且网络延迟敏感的情况下非常有用。该变量的默认设置为 false。如果设置为 true，则指示 CURL 将 HTTP 请求标头和正文有效载荷一起发送。

**disableIMDS**  
控制是否禁用实例元数据服务（IMDS）调用。默认设置为 false。设置为 true 可在 EC2 实例之外运行时禁用 IMDS 调用。

**disableImdsV1**  
控制是否在允许 IMDSv2 的同时禁用 IMDSv1 调用。默认设置为 false。设置为 true 可仅禁用 IMDSv1 调用以增强安全性。

**enableClockSkewAdjustment**  
控制每次 HTTP 尝试后是否调整时钟偏差。默认设置为 false。

**enableEndpointDiscovery**  
控制是否使用端点发现。默认情况下，将使用区域或被覆盖的端点。要启用端点发现，请将此变量设置为 true。

**enableHostPrefixInjection**  
控制 HTTP 主机是否向 DiscoverInstances 请求添加“data-”前缀。默认情况下，启用此行为。要禁用此行为，请将此变量设置为 false。

**enableHttpClientTrace**  
控制是否出于调试目的启用 HTTP 客户端跟踪。默认设置为 false。设置为 true 将会启用详细的 HTTP 请求和响应日志记录。

**enableTcpKeepAlive**  
控制是否发送 TCP 保持连接数据包。默认设置为 true。与 `tcpKeepAliveIntervalMs` 变量结合使用。此变量不适用于 WinINet 和 IXMLHTTPRequest2 客户端。

**endpointOverride**  
指定用于与服务通信的覆盖 HTTP 端点。

**executor**  
引用异步执行器处理程序的实现。默认行为是为每个异步调用创建和分离线程。要更改此行为，请实现 `Executor` 类的一个子类并为该变量分配一个实例。

**followRedirects**  
控制处理 HTTP 300 重定向代码时的行为。

**httpLibOverride**  
指定默认 HTTP 工厂返回的 HTTP 实现。Windows 的默认 HTTP 客户端是 WinHTTP。所有其他平台的默认 HTTP 客户端均为 CURL。

**httpLibPerfMode**  
指定 HTTP 库的性能模式。默认设置为 LOW\$1LATENCY。您可以调整此设置以针对不同的性能特征进行优化。

**httpRequestTimeoutMs**  
指定 HTTP 请求超时（以毫秒为单位）。默认值为 0（无超时）。传输大文件时，请考虑增加此值。

**lowSpeedLimit**  
指定允许的最低传输速度（以每秒字节为单位）。如果传输速度低于指定速度，则传输操作将中止。默认设置为 1 字节/秒。此变量仅适用于 CURL 客户端。

**maxConnections**  
指定与单个服务器的 HTTP 的最大 HTTP 连接数。默认值为 25。除您的带宽实际可支持的范围外，无其他最大允许值限制。

**nonProxyHosts**  
指定应绕过代理设置的主机名数组。使用此设置可将特定主机排除在代理配置之外。

**profileName**  
指定要用于配置的 AWS 配置文件（profile）名称。SDK 会从 AWS 配置文件中指定的配置文件（profile）加载设置。

**proxyCaFile**  
指定代理连接的证书颁发机构文件路径，当该路径与默认路径不同时使用。

**proxyCaPath**  
指定代理连接的证书颁发机构信任存储路径，当该路径与默认路径不同时使用。

**proxyScheme、proxyHost、proxyPort、proxyUserName 和 proxyPassword**  
用于为与 AWS 的所有通信设置和配置代理。该功能的适用场景示例包括：结合 Burp Suite 进行调试，或通过代理连接互联网。

**proxySSLCertPath**  
为需要客户端证书的代理连接指定 SSL 证书文件的路径。

**proxySSLCertType**  
指定用于代理连接的 SSL 证书类型。常见类型包括 PEM 和 DER。

**proxySSLKeyPassword**  
指定代理连接中使用的 SSL 私钥的密码，前提是该私钥受密码保护。

**proxySSLKeyPath**  
为需要客户端证书的代理连接指定 SSL 私钥文件的路径。

**proxySSLKeyType**  
指定用于代理连接的 SSL 私钥类型。常见类型包括 PEM 和 DER。

**writeRateLimiter 和 readRateLimiter**  
对读/写速率限制器实现的引用，这些限制器用于限制传输层的带宽使用。默认情况下，读取和写入速率不受限制。要引入限制功能，请实现 `RateLimiterInterface` 的一个子类并为这些变量分配一个实例。

**区域**  
指定要使用的 AWS 区域，例如 *us-east-1*。默认情况下，使用的区域是在适用的 AWS 凭证中配置的默认区域。

**requestCompressionConfig**  
包含请求压缩的配置设置。使用此结构控制请求在传输前的压缩时机与压缩方式。

**retryStrategy**  
引用重试策略的实现。默认策略实现指数回退策略。要执行不同的策略，请实现 `RetryStrategy` 类的子类并为该变量分配一个实例。

**scheme**  
指定 URI 寻址方案（HTTP 或 HTTPS）。默认方案是 HTTPS。

**tcpKeepAliveIntervalMs**  
指定通过 TCP 连接发送保持连接（keep-alive）数据包的时间间隔（以毫秒为单位）。默认间隔为 30 秒。最小设置为 15 秒。此变量不适用于 WinINet 和 IXMLHTTPRequest2 客户端。

**telemetryProvider**  
引用遥测提供程序实现来收集指标和跟踪数据。配置此设置来启用可观测性功能。

**userAgent**  
仅供内部使用。请勿更改此变量的设置。

**useDualStack**  
控制是否使用 IPv4 和 IPv6 双栈端点。请注意，并非所有 AWS 服务在所有区域都支持 IPv6。

**useFIPS**  
控制是否使用经过联邦信息处理标准（FIPS）140-2 验证的加密模块。默认设置为 false。如果需要实现 FIPS 合规性，则设置为 true。

**verifySSL**  
控制是否验证 SSL 证书。默认情况下将验证 SSL 证书。要禁用验证，请将变量设置为 false。

**version**  
指定用于请求的 HTTP 版本。默认设置为 HTTP\$1VERSION\$12TLS（基于 TLS 的 HTTP/2）。

**winHTTPOptions**  
包含特定于 Windows 的 HTTP 配置选项。包括 useAnonymousAuth，默认设置为 false。