本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在程式碼中設定適用於 C\$1\$1 服務用戶端的 AWS SDK
<a name="client-config"></a>

直接在程式碼中處理組態時，組態範圍僅限於使用該程式碼的應用程式。在該應用程式中，有所有服務用戶端的全域組態、特定 AWS 服務 類型之所有用戶端的組態，或特定服務用戶端執行個體的組態等選項。

 適用於 C\$1\$1 的 AWS SDK 包含 AWS 服務 用戶端類別，可提供與 AWS 服務 您在應用程式中使用的 互動的功能。在適用於 C\$1\$1 的 開發套件中，您可以變更預設用戶端組態，這在您想要執行下列動作時很有幫助：
+ 透過代理連線到網際網路
+ 變更 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**  
控制以帳戶為基礎的端點路由行為。有效值為「必要」、「停用」或「偏好」。預設值為「偏好」。設為「停用」以在必要時關閉以帳戶為基礎的端點路由。

**allowSystemProxy**  
控制 HTTP 用戶端是否探索系統代理設定。預設設定為 false。設定為 true 以啟用自動代理探索。

**appId**  
指定選用的應用程式特定識別符。設定時，此值會以 格式附加至 `User-Agent`標頭`App/{appId}`。您可以使用`AWS_SDK_UA_APP_ID`環境變數或`sdk_ua_app_id`共用組態描述檔屬性來設定此值。

**caPath、caFile**  
指示 HTTP 用戶端在何處找到您的 SSL 憑證信任存放區。範例信任存放區可能是使用 OpenSSL `c_rehash`公用程式準備的目錄。除非您的環境使用符號連結，否則不應設定這些變數。這些變數不會影響 Windows 和 macOS 系統。

**checksumConfig**  
包含檢查總和計算和驗證設定。包含`responseChecksumValidation`預設值為 WHEN\$1SUPPORTED 的 `requestChecksumCalculation`和 。

**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**  
控制在允許 IMDSv1 時是否停用 IMDSv2 呼叫。預設設定為 false。設為 true 可僅停用 IMDSv1 呼叫以增強安全性。

**enableClockSkewAdjustment**  
控制是否在每次 HTTP 嘗試後調整時鐘扭曲。預設設定為 false。

**enableEndpointDiscovery**  
控制是否使用端點探索。根據預設，會使用區域或覆寫端點。若要啟用端點探索，請將 變數設定為 true。

**enableHostPrefixInjection**  
控制 HTTP 主機是否將「資料」字首新增至 DiscoverInstances 請求。預設會啟用此行為。若要停用它，請將 變數設定為 false。

**enableHttpClientTrace**  
控制是否啟用 HTTP 用戶端追蹤進行偵錯。預設設定為 false。設定為 true 以啟用詳細的 HTTP 請求和回應記錄。

**enableTcpKeepAlive**  
控制是否要傳送 TCP 保持連線封包。預設設定為 true。搭配 `tcpKeepAliveIntervalMs`變數使用 。此變數不適用於 WinINet 和 IXMLHTTPRequest2 用戶端。

**endpointOverride**  
指定要與服務通訊的覆寫 HTTP 端點。

**執行器**  
參考非同步執行器處理常式的實作。預設行為是為每個非同步呼叫建立和分離執行緒。若要變更此行為，請實作 `Executor` 類別的子類別，並將執行個體指派給此變數。

**followRedirects**  
控制處理 HTTP 300 重新導向代碼時的行為。

**httpLibOverride**  
指定預設 HTTP 工廠傳回的 HTTP 實作。Windows 的預設 HTTP 用戶端為 WinHTTP。所有其他平台的預設 HTTP 用戶端為 CURL。

**httpLibPerfMode**  
指定 HTTP 程式庫效能模式。預設設定為 LOW\$1LATENCY。您可以調整此設定來最佳化不同的效能特性。

**httpRequestTimeoutMs**  
以毫秒為單位指定 HTTP 請求逾時。預設值為 0 （無逾時）。傳輸大型檔案時，請考慮增加此值。

**lowSpeedLimit**  
以每秒位元組為單位指定允許的最小傳輸速度。如果傳輸速度低於指定的速度，則傳輸操作會中止。預設設定為 1 位元組/秒。此變數僅適用於 CURL 用戶端。

**maxConnections**  
指定單一伺服器的 HTTP 連線數目上限。預設值為 25。除了頻寬可合理支援的值之外，沒有允許的最大值。

**nonProxyHosts**  
指定應該略過代理設定的主機名稱陣列。使用此設定從代理組態中排除特定主機。

**profileName**  
指定用於組態的 AWS 設定檔名稱。SDK 會從 AWS 組態檔案中指定的設定檔載入設定。

**proxyCaFile**  
當代理連線與預設連線不同時，指定憑證授權單位檔案的路徑。

**proxyCaPath**  
當代理連線與預設連線不同時，指定憑證授權機構信任存放區的路徑。

**proxyScheme、proxyHost、proxyPort、proxyUserName 和 proxyPassword**  
用來設定和設定所有 通訊的代理 AWS。此功能可能有用的範例包括搭配 Burp 套件進行偵錯，或使用代理連線到網際網路。

**proxySSLCertPath**  
指定需要用戶端憑證之代理連線的 SSL 憑證檔案路徑。

**proxySSLCertType**  
指定代理連線的 SSL 憑證類型。常見類型包括 PEM 和 DER。

**proxySSLKeyPassword**  
指定金鑰受到密碼保護時，用於代理連線的 SSL 私有金鑰的密碼。

**proxySSLKeyPath**  
指定需要用戶端憑證之代理連線的 SSL 私有金鑰檔案路徑。

**proxySSLKeyType**  
指定代理連線的 SSL 私有金鑰類型。常見類型包括 PEM 和 DER。

**writeRateLimiter 和 readRateLimiter**  
參考用於調節傳輸層所用頻寬的讀取和寫入速率限制器實作。根據預設，讀取和寫入速率不會調節。若要引入限流，請實作 的子類別，`RateLimiterInterface`並將執行個體指派給這些變數。

**region**  
指定要使用 AWS 的區域，例如 *us-east-1*。根據預設，使用的區域是適用的 AWS 登入資料中設定的預設區域。

**requestCompressionConfig**  
包含請求壓縮的組態設定。使用此結構來控制在傳輸前壓縮請求的時間和方式。

**retryStrategy**  
參考重試策略的實作。預設策略會實作指數退避政策。若要執行不同的策略，請實作 `RetryStrategy` 類別的子類別，並將執行個體指派給此變數。

**結構描述**  
指定 HTTP 或 HTTPS 的 URI 定址機制。預設方案為 HTTPS。

**tcpKeepAliveIntervalMs**  
指定透過 TCP 連線傳送持續連線封包的時間間隔，以毫秒為單位。預設間隔為 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 (HTTP/2 over TLS)。

**winHTTPOptions**  
包含 Windows 特定的 HTTP 組態選項。包含具有預設設定 false 的 useAnonymousAuth。