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

# 在適用於 Rust 的 AWS SDK 中設定服務用戶端
<a name="configure"></a>

 若要以程式設計方式存取 AWS 服務，適用於 Rust 的 AWS SDK 會為每個 使用用戶端結構 AWS 服務。例如，如果您的應用程式需要存取 Amazon EC2，您的應用程式會建立 Amazon EC2 用戶端結構，以與該服務連接。然後，您可以使用 服務用戶端向該用戶端提出請求 AWS 服務。

若要向 提出請求 AWS 服務，您必須先建立服務用戶端。對於 AWS 服務 每個程式碼使用，它都有自己的木箱和自己的專用類型來與其互動。用戶端會針對服務公開的每個 API 操作公開一個方法。

設定 SDK 行為有許多替代方法，但最終一切都與服務用戶端的行為有關。使用從中建立的服務用戶端之前，任何組態都不會生效。

當您使用 開發 AWS 時，您必須建立程式碼向 進行身分驗證的方式 AWS 服務。您也必須設定 AWS 區域 您要使用的 。

[AWS SDKs和工具參考指南](https://docs.aws.amazon.com/sdkref/latest/guide/)也包含許多 AWS SDKs 中常見的設定、功能和其他基本概念。

**Topics**
+ [外部用戶端組態](config-external.md)
+ [程式碼中的用戶端組態](config-code.md)
+ [AWS 區域](region.md)
+ [登入資料提供者](credproviders.md)
+ [行為版本](behavior-versions.md)
+ [重試](retries.md)
+ [逾時](timeouts.md)
+ [可觀測性](observability.md)
+ [用戶端端點](endpoints.md)
+ [覆寫 操作組態](peroperation.md)
+ [HTTP](http.md)
+ [攔截器](interceptors.md)

# 在外部設定 適用於 Rust 的 AWS SDK 服務用戶端
<a name="config-external"></a>

許多組態設定可以在程式碼之外處理。在外部處理組態時，組態會套用至所有應用程式。大多數組態設定可以設定為環境變數或單獨的共用 AWS `config`檔案中。共用`config`檔案可以維護個別的設定集，稱為設定檔，為不同的環境或測試提供不同的組態。

環境變數和共用`config`檔案設定會在 SDKs 和工具之間 AWS 標準化和共用，以支援不同程式設計語言和應用程式的一致功能。

請參閱 *AWS SDKs和工具參考指南*，了解如何透過這些方法設定您的應用程式，以及每個跨 sdk 設定的詳細資訊。若要查看開發套件可從環境變數或組態檔案解析的所有設定，請參閱開發套件和工具參考指南中的[設定](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html)參考。 *AWS SDKs *

若要向 提出請求 AWS 服務，您必須先執行個體化該服務的用戶端。您可以設定服務用戶端的常見設定，例如逾時、HTTP 用戶端和重試組態。

每個服務用戶端都需要 AWS 區域 和登入資料提供者。SDK 使用這些值將請求傳送到 資源的正確區域，並使用正確的登入資料簽署請求。您可以在程式碼中以程式設計方式指定這些值，或從環境中自動載入這些值。

開發套件有一系列位置 （或來源） 可供其檢查，以尋找組態設定的值。

1. 程式碼中或服務用戶端本身上設定的任何明確設定，都優先於任何其他設定。

1. 環境變數
   + 如需設定環境變數的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[環境變數](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html)。
   + 請注意，您可以為殼層設定不同範圍的環境變數：全系統、全使用者和特定終端機工作階段。

1. 共用 `config`和 `credentials` 檔案
   + 如需設定這些檔案的詳細資訊，請參閱 SDK [`config`和工具參考指南中的共用 和 `credentials` 檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。 *AWS SDKs *

1. 開發套件原始碼本身提供的任何預設值都會最後使用。
   + 有些屬性，例如區域，沒有預設值。您必須在程式碼、環境設定或共用`config`檔案中明確指定它們。如果 SDK 無法解析所需的組態，API 請求可能會在執行時間失敗。

# 在程式碼中設定適用於 Rust 服務用戶端的 AWS SDK
<a name="config-code"></a>

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

若要向 提出請求 AWS 服務，您必須先執行個體化該服務的用戶端。您可以設定服務用戶端的常見設定，例如逾時、HTTP 用戶端和重試組態。

每個服務用戶端都需要 AWS 區域 和登入資料提供者。SDK 使用這些值將請求傳送到 資源的正確區域，並使用正確的登入資料簽署請求。您可以在程式碼中以程式設計方式指定這些值，或從環境中自動載入這些值。

**注意**  
服務用戶端的建構成本可能很昂貴，通常需要共用。為了促進這一點，所有`Client`結構都會實作 `Clone`。

## 從環境設定用戶端
<a name="configure-a-client-from-the-environment"></a>

若要建立具有環境來源組態的用戶端，請使用 `aws-config` 木箱中的靜態方法：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .load()
    .await;

let s3 = aws_sdk_s3::Client::new(&config);
```

以這種方式建立用戶端在 Amazon Elastic Compute Cloud 上執行時很有用 AWS Lambda，或是可在環境中直接使用服務用戶端組態的任何其他內容。這會將您的程式碼與執行環境分離，讓您更輕鬆地將應用程式部署到多個 ， AWS 區域 而無需變更程式碼。

您可以明確覆寫特定屬性。明確組態優先於從執行環境解析的組態。下列範例會從環境載入組態，但明確覆寫 AWS 區域：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .region("us-east-1")
    .load()
    .await;
    
let s3 = aws_sdk_s3::Client::new(&config);
```

**注意**  
並非所有組態值都是由用戶端在建立時取得。當用戶端用於提出請求時，登入資料提供者層會存取登入資料相關設定，例如臨時存取金鑰和 IAM Identity Center 組態。

先前範例中`BehaviorVersion::latest()`顯示的程式碼指出要用於預設值的 SDK 版本。 `BehaviorVersion::latest()`適用於大多數情況。如需詳細資訊，請參閱[在 中使用行為版本 適用於 Rust 的 AWS SDK](behavior-versions.md)。

## 將建置器模式用於服務特定的設定
<a name="configure-a-client-builder"></a>

有些選項只能在特定服務用戶端類型上設定。不過，大多數情況下，您仍然想要從環境載入大部分的組態，然後特別新增其他選項。建置器模式是木 適用於 Rust 的 AWS SDK 箱內的常見模式。您首先使用 載入一般組態`aws_config::defaults`，然後使用 `from`方法將該組態載入您正在使用的 服務的建置器。然後，您可以為該服務設定任何唯一的組態值，並呼叫 `build`。最後，會從此修改後的組態建立用戶端。

```
// Call a static method on aws-config that sources default config values.
let config = aws_config::defaults(BehaviorVersion::latest())
    .load()
    .await;

// Use the Builder for S3 to create service-specific config from the default config.
let s3_config = aws_sdk_s3::config::Builder::from(&config)
    .accelerate(true) // Set an S3-only configuration option
    .build();

// Create the client.
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```

探索特定服務用戶端類型可用的其他方法之一，就是使用 API 文件，例如 的 [https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html)。

## 進階明確用戶端組態
<a name="configure-a-client-explicitly"></a>

若要設定具有特定值的服務用戶端，而不是從環境載入組態，您可以在用戶端`Config`建置器上指定它們，如下所示：

```
let conf = aws_sdk_s3::Config::builder()
    .region("us-east-1")
    .endpoint_resolver(my_endpoint_resolver)
    .build();

let s3 = aws_sdk_s3::Client::from_conf(conf);
```

當您使用 建立服務組態時`aws_sdk_s3::Config::builder()`，*不會載入任何預設組態*。預設值只會在根據 建立組態時載入`aws_config::defaults`。

有些選項只能在特定服務用戶端類型上設定。上一個範例顯示在 Amazon S3 用戶端上使用 `endpoint_resolver`函數的範例。

# 設定 AWS 區域 的 適用於 Rust 的 AWS SDK
<a name="region"></a>

您可以使用 存取在特定地理區域中操作 AWS 服務 的 AWS 區域。這對於備援和讓資料和應用程式靠近您和您的使用者存取它們的位置，都很有用。如需如何使用區域的詳細資訊，請參閱《 *AWS SDKs與工具參考指南*[AWS 區域](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)》中的 。

**重要**  
大多數資源都位於特定 中， AWS 區域 您必須在使用 SDK 時為資源提供正確的區域。

您必須設定 SDK for Rust AWS 區域 的預設值，以用於 AWS 請求。此預設值用於非以 區域指定的任何 SDK 服務方法呼叫。

如需如何透過共用 AWS `config`檔案或環境變數設定預設區域的範例，請參閱《 *AWS SDKs與工具參考指南*[AWS 區域](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)》中的 。

## AWS 區域 供應商鏈結
<a name="region-provider-chain"></a>

 從執行環境載入服務用戶端的組態時，會使用下列查詢程序。軟體開發套件尋找的第一個值用於用戶端的組態中。如需建立服務用戶端的詳細資訊，請參閱 [從環境設定用戶端](config-code.md#configure-a-client-from-the-environment)。

1. 任何以程式設計方式設定的明確區域。

1. 檢查 `AWS_REGION` 環境變數。
   + 如果您使用 AWS Lambda 服務，容器會自動設定此環境變數 AWS Lambda 。

1. 會檢查共用 AWS `config`檔案中的 `region` 屬性。
   + `AWS_CONFIG_FILE` 環境變數可用來變更共用`config`檔案的位置。若要進一步了解保留此檔案的位置，請參閱 SDK [`config`和工具參考指南中的共用和`credentials`檔案的位置](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)。 *AWS SDKs *
   + `AWS_PROFILE` 環境變數可用來選取具名設定檔，而非預設值。若要進一步了解如何設定不同的設定檔，請參閱 SDK [`config`和工具參考指南中的共用和`credentials`檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。 *AWS SDKs *

1. SDK 會嘗試使用 Amazon EC2 執行個體中繼資料服務來判斷目前執行中 Amazon EC2 執行個體的區域。
   +  適用於 Rust 的 AWS SDK 僅支援 IMDSv2。

建立基本組態以與服務用戶端搭配使用時， `RegionProviderChain` 會自動使用，無需額外的程式碼：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .load()
    .await;
```

## 在程式碼 AWS 區域 中設定
<a name="RegionProgram"></a>

### 在程式碼中明確設定區域
<a name="RegionNew"></a>

當您想要明確設定區域時，請`Region::new()`直接在組態中使用 。

不使用區域提供者鏈結 - 它不會檢查環境、共用`config`檔案或 Amazon EC2 執行個體中繼資料服務。

```
use aws_config::{defaults, BehaviorVersion};
use aws_sdk_s3::config::Region;

#[tokio::main]
async fn main() {
    let config = defaults(BehaviorVersion::latest())
        .region(Region::new("us-west-2"))
        .load()
        .await;

    println!("Using Region: {}", config.region().unwrap());
}
```

請確定您輸入的是 的有效字串 AWS 區域；所提供的值未經驗證。

### 自訂 `RegionProviderChain`
<a name="regionProviderChain"></a>

當您想要有條件地插入區域、覆寫區域或自訂解析度鏈[AWS 區域 供應商鏈結](#region-provider-chain)時，請使用 。

```
use aws_config::{defaults, BehaviorVersion};
use aws_config::meta::region::RegionProviderChain;
use aws_sdk_s3::config::Region;
use std::env;

#[tokio::main]
async fn main() {  
    let region_provider = RegionProviderChain::first_try(env::var("CUSTOM_REGION").ok().map(Region::new))
        .or_default_provider()
        .or_else(Region::new("us-east-2"));
    
    let config = aws_config::defaults(BehaviorVersion::latest())
        .region(region_provider)
        .load()
        .await;

    println!("Using Region: {}", config.region().unwrap());
}
```

 先前的組態將：

1. 首先查看`CUSTOM_REGION`環境變數中是否設定了字串。

1. 如果無法使用，請回到預設區域提供者鏈結。

1. 如果失敗，請使用「us-east-2」作為最終備用。

# 使用 AWS SDK for Rust 登入資料提供者
<a name="credproviders"></a>

 對 的所有請求 AWS 都必須使用 發行的登入資料以密碼編譯方式簽署 AWS。在執行時間，軟體開發套件會檢查多個位置來擷取登入資料的組態值。

如果擷取的組態包含[AWS IAM Identity Center 單一登入存取設定](credentials.md)，軟體開發套件會與 IAM Identity Center 搭配使用，以擷取用於提出請求的臨時登入資料 AWS 服務。

如果擷取的組態包含[臨時登入](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html)資料，軟體開發套件會使用它們來進行 AWS 服務 呼叫。暫時登入資料包含存取金鑰和工作階段字符。

使用 進行身分驗證 AWS 可以在您的程式碼庫之外處理。開發套件可以使用登入資料提供者鏈自動偵測、使用和重新整理許多身分驗證方法。

如需專案身分 AWS 驗證入門的引導選項，請參閱*AWS SDKs和工具參考指南》中的*[身分驗證和存取](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。

## 登入資料提供者鏈結
<a name="credproviders-default-credentials-provider-chain"></a>

如果您在建構用戶端時未明確指定登入資料提供者，適用於 Rust 的 SDK 會使用登入資料提供者鏈結來檢查您可以提供登入資料的一系列位置。一旦 SDK 在其中一個位置找到登入資料，搜尋就會停止。如需建構用戶端的詳細資訊，請參閱 [在程式碼中設定適用於 Rust 服務用戶端的 AWS SDK](config-code.md)。

下列範例不會在程式碼中指定登入資料提供者。SDK 使用登入資料提供者鏈結來偵測已在託管環境中設定的身分驗證，並使用該身分驗證來進行呼叫 AWS 服務。

```
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3 = aws_sdk_s3::Client::new(&config);
```

### 登入資料擷取順序
<a name="credproviders-credential-retrieval-order"></a>

登入資料提供者鏈結會使用下列預先定義的序列搜尋登入資料：

1. **存取金鑰環境變數**

   SDK 會嘗試從 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`以及 `AWS_SESSION_TOKEN`環境變數載入登入資料。

1. **共用 AWS `config` 和 `credentials` 檔案**

   SDK 會嘗試從共用 AWS `config` 和 `credentials` 檔案中的 `[default]` 設定檔載入登入資料。您可以使用 `AWS_PROFILE`環境變數來選擇您希望 SDK 載入的具名設定檔，而不是使用 `[default]`。`config` 和 `credentials` 檔案由 AWS SDKs和工具共用。如需這些檔案的詳細資訊，請參閱 SDK [`config`和工具參考指南中的共用 和 `credentials` 檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。 *AWS SDKs * 如需您可以在設定檔中指定之標準化提供者的詳細資訊，請參閱 [AWS SDKs和工具標準化憑證提供者](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)。

1. **AWS STS Web 身分**

   建立需要存取的行動應用程式或用戶端型 Web 應用程式時 AWS， AWS Security Token Service (AWS STS) 會為透過公有身分提供者 (IdP) 驗證的聯合身分使用者傳回一組臨時安全登入資料。
   + 當您在設定檔中指定此項目時，軟體開發套件或工具會嘗試使用 AWS STS `AssumeRoleWithWebIdentity` API 方法擷取臨時登入資料。如需此方法的詳細資訊，請參閱 *AWS Security Token Service API 參考*中的 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
   +  如需設定此提供者的指引，請參閱 *AWS SDKs和工具參考指南*中的[使用 Web 身分或 OpenID Connect 聯合](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#webidentity)。
   +  如需此供應商 SDK 組態屬性的詳細資訊，請參閱《 *AWS SDKs和工具參考指南*》中的[擔任角色登入資料供應商](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html)。

1. **Amazon ECS 和 Amazon EKS 容器憑證 **

   您的 Amazon Elastic Container Service 任務和 Kubernetes 服務帳戶可以具有與其相關聯的 IAM 角色。在 IAM 角色中授予的許可，是由在 Pod 任務或容器中執行的容器所擔任。此角色可讓您的 SDK for Rust 應用程式碼 （在容器上） 使用其他 AWS 服務。

   SDK 會嘗試從 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`或 `AWS_CONTAINER_CREDENTIALS_FULL_URI`環境變數擷取登入資料，這些變數可由 Amazon ECS 和 Amazon EKS 自動設定。
   + 如需為 Amazon ECS 設定此角色的詳細資訊，請參閱[《Amazon Elastic Container Service 開發人員指南》中的 Amazon ECS 任務 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)。 **
   + 如需 Amazon EKS 設定資訊，請參閱[《Amazon EKS 使用者指南》中的設定 Amazon EKS Pod Identity Agent](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html)。 ****
   +  如需此提供者 SDK 組態屬性的詳細資訊，請參閱 SDK *AWS SDKs 和工具參考指南*中的[容器憑證提供者](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html)。

1. **Amazon EC2 執行個體中繼資料服務 **

   建立 IAM 角色並將其連接至您的執行個體。執行個體上的 SDK for Rust 應用程式會嘗試從執行個體中繼資料擷取角色提供的登入資料。
   + SDK for Rust 僅支援 [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)。
   + 如需設定此角色和使用中繼資料的詳細資訊，請參閱《[Amazon EC2 使用者指南》中的 Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)和[使用執行個體中繼資料](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)。 *Amazon EC2 *
   +  如需此供應商 SDK 組態屬性的詳細資訊，請參閱《 *AWS SDKs和工具參考指南*》中的 [IMDS 登入資料供應商](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html)。

1. 如果目前仍無法解析登入資料，則操作會panics發生錯誤。

如需 AWS 登入資料提供者組態設定的詳細資訊，請參閱 *AWS SDKs和工具參考指南**的設定參考*中的[標準化登入資料提供者](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)。

## 明確登入資料提供者
<a name="credproviders-explicit-credentials-provider"></a>

您可以指定 SDK 應使用的特定登入資料提供者，而不是依賴登入資料提供者鏈來偵測您的身分驗證方法。當您使用 載入一般組態時`aws_config::defaults`，您可以指定自訂登入資料提供者，如下所示：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .credentials_provider(MyCredentialsProvider::new())
    .load()
    .await;
```

您可以透過實作 [https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html](https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html) 特性來實作自己的登入資料提供者。

## 身分快取
<a name="credproviders-identity-caching"></a>

SDK 會快取登入資料和其他身分類型，例如 SSO 字符。根據預設，開發套件會使用延遲快取實作，在第一次請求時載入登入資料、快取登入資料，然後在另一個請求接近過期時嘗試重新整理登入資料。從相同 建立的用戶端`SdkConfig`將共用 [https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html](https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html)。

# 在 中使用行為版本 適用於 Rust 的 AWS SDK
<a name="behavior-versions"></a>

適用於 Rust 的 AWS SDK 開發人員期望並依賴語言及其主要程式庫提供的強大且可預測的行為。為了協助開發人員使用適用於 Rust 的 SDK 取得預期的行為，用戶端組態需要包含 `BehaviorVersion`。`BehaviorVersion` 指定預設的 SDK 版本。這可讓 SDK 隨著時間演進，變更最佳實務以符合新標準，並支援新功能，而不會對您應用程式的行為造成非預期的負面影響。

**警告**  
如果您嘗試在未明確指定 的情況下設定 SDK 或建立用戶端`BehaviorVersion`，建構函數將會 panic。

例如，假設使用新的預設重試政策發行新版本的 SDK。如果您的應用程式使用`BehaviorVersion`符合先前版本的 SDK，則會使用該先前組態，而非新的預設組態。

每次發佈適用於 Rust 的 SDK 的新行為版本時，先前的 `BehaviorVersion` 都會以適用於 Rust 的 SDK `deprecated` 屬性標記，並新增新版本。這會導致在編譯時間發生警告，但否則可讓組建繼續照常進行。 `BehaviorVersion::latest()` 也會更新，以指出新版本的預設行為。

**注意**  
如果您的程式碼不依賴極端特定的行為特性，您應該在程式碼`BehaviorVersion::latest()`中使用 ，或使用 `Cargo.toml` `behavior-version-latest`檔案中的功能旗標。如果您要撰寫對延遲敏感的程式碼，或調整 Rust SDK 行為，請考慮鎖定`BehaviorVersion`至特定主要版本。

## 在 中設定行為版本 `Cargo.toml`
<a name="set-the-behavior-version-in-cargo-toml"></a>

您可以在 `Cargo.toml` 檔案中包含適當的功能旗標，以指定 SDK 和個別模組的行為版本`aws-sdk-iam`，例如 `aws-sdk-s3`或 。目前， 僅支援 開發套件的 `latest`版本`Cargo.toml`：

```
[dependencies]
aws-config = { version = "1", features = ["behavior-version-latest"] }
aws-sdk-s3 = { version = "1", features = ["behavior-version-latest"] }
```

## 在程式碼中設定行為版本
<a name="set-the-behavior-version-in-code"></a>

您的程式碼可以視需要變更行為版本，方法是在設定 SDK 或用戶端時加以指定：

```
let config = aws_config::load_defaults(BehaviorVersion::v2023_11_09()).await;
```

此範例會建立使用環境來設定 SDK，但將 `BehaviorVersion`設定為 的組態`v2023_11_09()`。

# 在適用於 Rust 的 AWS SDK 中設定重試
<a name="retries"></a>

SDK AWS for Rust 為服務請求和可自訂組態選項提供預設的重試行為。呼叫 AWS 服務 偶爾會傳回未預期的例外狀況。如果重試呼叫，某些類型的錯誤可能會成功，例如限流或暫時性錯誤。

您可以使用共用 AWS `config`檔案中的環境變數或設定，全域設定重試行為。如需此方法的資訊，請參閱 *AWS SDKs和工具參考指南*中的[重試行為](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)。它還包含重試策略實作的詳細資訊，以及如何逐一選擇。

或者，您也可以在程式碼中設定這些選項，如下列各節所示。

## 預設重試組態
<a name="defaultRetryConfig"></a>

 每個服務用戶端都會預設為透過 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) 結構提供的`standard`重試策略組態。根據預設，會嘗試三次通話 *（初次嘗試，加上兩次重試*)。此外，每次重試都會延遲一小段的隨機持續時間，以避免重試風暴。此慣例適用於大多數使用案例，但在高輸送量系統等特定情況下可能不合適。

 只有某些類型的錯誤會被 SDKs 視為可重試。可重試錯誤的範例如下：
+ 通訊端逾時
+ 服務端限流
+ HTTP 5XX 回應等暫時性服務錯誤

下列範例**不**被視為可重試：
+ 缺少參數或其無效
+ 身分驗證/安全錯誤
+ 設定錯誤例外狀況

您可以透過設定最大嘗試次數、延遲和退避組態來自訂`standard`重試策略。

## 最大嘗試次數
<a name="maxAttempts"></a>

您可以將修改過的 提供給 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)，以自訂程式碼中的最大嘗試次數`aws_config::defaults`：

```
const CUSTOM_MAX_ATTEMPTS: u32 = 5;
let retry_config = RetryConfig::standard()
    // Set max attempts. When max_attempts is 1, there are no retries.
    // This value MUST be greater than zero.
    // Defaults to 3.
    .with_max_attempts(CUSTOM_MAX_ATTEMPTS);
  
let config = aws_config::defaults(BehaviorVersion::latest())
    .retry_config(retry_config)
    .load()
    .await;
```

## 延遲和退避
<a name="delays"></a>

如果需要重試，預設重試策略會在進行後續嘗試之前等待。第一次重試的延遲很小，但之後重試會呈指數增長。延遲的最大數量會受到限制，使其不會太大。

隨機抖動會套用至所有嘗試之間的延遲。抖動有助於減輕可能導致重試風暴的大型機群的影響。如需指數退避和抖動的深入討論，請參閱 *AWS 架構部落格*中的[指數退避和抖動](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)。

 您可以將修改後的 提供給 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)，以自訂程式碼中的延遲設定`aws_config::defaults`。下列程式碼會將組態設定為將第一次重試嘗試延遲最多 100 毫秒，且任何重試嘗試之間的時間上限為 5 秒。

```
let retry_config = RetryConfig::standard()
    // Defaults to 1 second.
    .with_initial_backoff(Duration::from_millis(100))
    // Defaults to 20 seconds.
    .with_max_backoff(Duration::from_secs(5));
  
let config = aws_config::defaults(BehaviorVersion::latest())
    .retry_config(retry_config)
    .load() 
    .await;
```

## 自適應重試模式
<a name="AdaptiveRetryMode"></a>

 作為`standard`模式重試策略的替代方案，`adaptive`模式重試策略是一種進階方法，可尋求理想的請求率，以將限流錯誤降至最低。

**注意**  
自適應重試是一種進階重試模式。通常不建議使用此策略。請參閱 *AWS SDKs和工具參考指南*中的[重試行為](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html#standardvsadaptive)。

自適應重試包含標準重試的所有功能。它會新增用戶端速率限制器，測量節流請求相較於非節流請求的速率。它也會限制流量以嘗試保持在安全頻寬內，理想情況下會導致零限流錯誤。

速率會即時適應不斷變化的服務條件和流量模式，並可能相應地增加或減少流量速率。重要的是，速率限制器可能會延遲高流量案例中的初始嘗試。

您可以提供修改過的 ，在程式碼中選取`adaptive`重試策略[https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .retry_config(RetryConfig::adaptive())
    .load()
    .await;
```

# 在適用於 Rust 的 AWS SDK 中設定逾時
<a name="timeouts"></a>

SDK AWS for Rust 提供多種設定，用於管理 AWS 服務 請求逾時和停滯的資料串流。這些可協助您的應用程式在網路中發生意外的延遲和故障時，以最佳方式運作。

## API 逾時
<a name="api-timeouts"></a>

當暫時性問題可能導致請求嘗試長時間或完全失敗時，請務必檢閱和設定逾時，以便您的應用程式可以快速失敗並採取最佳行為。開發套件可以自動重試失敗的請求。最佳實務是設定個別嘗試和整個請求的逾時。

SDK for Rust 提供預設逾時，用於建立請求的連線。開發套件沒有為接收請求嘗試或整個請求的回應設定任何預設最長等待時間。可使用下列逾時選項：


| 參數 | 預設值 | Description | 
| --- | --- | --- | 
| 連線逾時 | 3.1 秒 | 放棄之前等待建立連線的時間上限。 | 
| 操作逾時 | 無 | 從適用於 Rust 的 SDK 接收回應之前所等待的時間上限，包括所有重試。 | 
| 操作嘗試逾時 | 無 | 等待單一 HTTP 嘗試的時間上限，之後可重試 API 呼叫。 | 
| 讀取逾時 | 無 | 從請求啟動時間開始，等待讀取回應第一個位元組的時間上限。 | 

下列範例顯示具有自訂逾時值的 Amazon S3 用戶端組態：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .timeout_config(
        TimeoutConfig::builder()
            .operation_timeout(Duration::from_secs(5))
            .operation_attempt_timeout(Duration::from_millis(1500))
            .build()
    )
    .load()
    .await;

let s3 = aws_sdk_s3::Client::new(&config);
```

當您同時使用 操作和嘗試逾時時，您可以針對所有重試嘗試所花費的總時間設定硬性限制。您也可以將個別 HTTP 請求設定為在慢速請求上快速失敗。

除了在所有 操作的服務用戶端上設定這些逾時值之外，您也可以[針對單一請求 設定或覆寫這些](peroperation.md)逾時值。

**重要**  
操作和嘗試逾時不適用於在 SDK for Rust 傳回回應之後使用的串流資料。例如，從回應`ByteStream`的成員取用資料不會受到操作逾時的影響。

## 停滯的串流保護
<a name="stalled-stream-protection"></a>

SDK for Rust 提供另一種與偵測停滯串流相關的逾時形式。停滯串流是一種上傳或下載串流，不會產生超過設定的寬限期的資料。這有助於防止應用程式無限期地懸置，且永遠不會進行進度。

 當串流閒置的時間超過可接受的期間時，停滯的串流保護將傳回錯誤。

依預設，適用於 Rust 的 SDK 會針對上傳和下載啟用停滯的串流保護，並尋找至少 1 位元組/秒的活動，並有 20 秒的寬廣寬限期。

下列範例顯示的自訂 `StalledStreamProtectionConfig`會停用上傳保護，並將沒有活動的寬限期變更為 10 秒：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .stalled_stream_protection(
        StalledStreamProtectionConfig::enabled()
            .upload_enabled(false)
            .grace_period(Duration::from_secs(10))
            .build()
    )
    .load()
    .await;
```

**警告**  
停滯的串流保護是進階組態選項。建議您只在應用程式需要更緊密的效能，或造成其他問題時，才變更這些值。

### 停用停滯的串流保護
<a name="disable-stalled-stream-protection"></a>

下列範例示範如何完全停用停滯的串流保護：

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .stalled_stream_protection(StalledStreamProtectionConfig::disabled())
    .load()
    .await;
```

# 在適用於 Rust 的 AWS SDK 中設定可觀測性功能
<a name="observability"></a>

 可觀測性是從系統發出的資料推斷系統目前狀態的程度。發出的資料通常稱為遙測。

**Topics**
+ [日誌](logging.md)

# 在適用於 Rust 的 AWS SDK 中設定和使用記錄
<a name="logging"></a>

 適用於 Rust 的 AWS SDK 使用[追蹤](http://tracing.rs/)架構進行記錄。若要啟用記錄，請新增`tracing-subscriber`木箱，並在 Rust 應用程式中初始化木箱。日誌包括時間戳記、日誌層級和模組路徑，有助於偵錯 API 請求和 SDK 行為。使用 `RUST_LOG`環境變數來控制日誌詳細程度，並視需要依模組篩選。

## 如何在適用於 Rust 的 AWS SDK 中啟用記錄
<a name="enableLogging"></a>

1. 在專案目錄的命令提示中，新增[追蹤訂閱者](https://crates.io/crates/tracing-subscriber)目錄做為相依性：

   ```
   $ cargo add tracing-subscriber --features tracing-subscriber/env-filter
   ```

   這會將 木箱新增至 `Cargo.toml` 檔案的 `[dependencies]`區段。

1. 初始化訂閱者。通常先在 `main`函數中完成此操作，然後再呼叫任何適用於 Rust 的 SDK 操作：

   ```
   use aws_config::BehaviorVersion;
   
   type BoxError = Box<dyn Error + Send + Sync>;
   
   #[tokio::main]
   async fn main() -> Result<(), BoxError> {
       tracing_subscriber::fmt::init();  // Initialize the subscriber.
       
       let config = aws_config::defaults(BehaviorVersion::latest())
           .load()
           .await;
   
       let s3 = aws_sdk_s3::Client::new(&config);
   
       let _resp = s3.list_buckets()
           .send()
           .await?;
   
       Ok(())               
   }
   ```

1. 使用`RUST_LOG`環境變數開啟記錄。若要啟用記錄資訊的顯示，請在命令提示字元中，將`RUST_LOG`環境變數設定為您要記錄的層級。下列範例會將記錄設定為 `debug`層級：

------
#### [ Linux/macOS ]

   ```
   $ RUST_LOG=debug
   ```

------
#### [ Windows ]

   如果您使用的是 VSCode，終端機視窗通常會預設為 PowerShell。驗證您正在使用的提示類型。

   ```
   C:\> set RUST_LOG=debug
   ```

------
#### [ PowerShell ]

   ```
   PS C:\> $ENV:RUST_LOG="debug"
   ```

------

1. 執行程式：

   ```
   $ cargo run
   ```

   您應該會在主控台或終端機視窗中看到其他輸出。

如需詳細資訊，請參閱 文件中的[使用環境變數篩選事件](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables)`tracing-subscriber`。

## 解譯日誌輸出
<a name="logging-understanding"></a>

按照上一節中的步驟開啟記錄後，預設會將其他日誌資訊列印為標準輸出。

如果您使用的是預設日誌輸出格式 （由追蹤模組稱為「完整」)，您在日誌輸出中看到的資訊如下所示：

```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```

每個項目都包含下列項目：
+ 日誌項目的時間戳記。
+ 項目的日誌層級。這是一個字詞，例如 `INFO`、 `DEBUG`或 `TRACE`。
+ 產生日誌項目的巢狀[範圍](https://docs.rs/tracing/latest/tracing/span/index.html)集，以冒號 ("：") 分隔。這可協助您識別日誌項目的來源。
+ Rust 模組路徑，其中包含產生日誌項目的程式碼。
+ 記錄訊息文字。

追蹤模組的標準輸出格式使用 ANSI 逸出碼來將輸出著色。篩選或搜尋輸出時，請記住這些逸出序列。

**注意**  
`sdk_invocation_id` 出現在巢狀範圍集合中的 是由 SDK 產生的唯一 ID 用戶端，以協助關聯日誌訊息。它與在來自 的回應中找到的請求 ID 無關 AWS 服務。

## 微調您的記錄層級
<a name="logging-control"></a>

如果您使用支援環境篩選的木箱，例如 `tracing_subscriber`，您可以依模組控制日誌的詳細資訊。

您可以為每個模組開啟相同的記錄層級。下列會將`trace`每個模組的記錄層級設定為 ：

```
$ RUST_LOG=trace cargo run
```

您可以開啟特定模組的追蹤層級記錄。在下列範例中，只有來自 的日誌`aws_smithy_runtime`會傳入 `trace`層級。

```
$ RUST_LOG=aws_smithy_runtime=trace
```

您可以為多個模組指定不同的日誌層級，方法是使用逗號分隔它們。下列範例會將`aws_config`模組設定為`trace`關卡記錄，並將`aws_smithy_runtime`模組設定為`debug`關卡記錄。

```
$ RUST_LOG=aws_config=trace,aws_smithy_runtime=debug cargo run
```

下表說明您可以用來篩選日誌訊息的一些模組：


| 字首 | 描述 | 
| --- | --- | 
|  `aws_smithy_runtime`  |  請求和回應線路記錄  | 
|  `aws_config`  |  登入資料載入  | 
|  `aws_sigv4`  |  請求簽署和正式請求  | 

了解您需要在日誌輸出中包含哪些模組的一種方法是先記錄所有項目，然後在日誌輸出中尋找所需資訊的木箱名稱。然後，您可以相應地設定環境變數，然後再次執行您的程式。

# 在 中設定用戶端端點 適用於 Rust 的 AWS SDK
<a name="endpoints"></a>

當 適用於 Rust 的 AWS SDK 呼叫 時 AWS 服務，第一個步驟是判斷路由請求的位置。此程序稱為端點解析。

您可以在建立服務用戶端時設定 SDK 的端點解析。端點解析的預設組態通常沒問題，但您可能想要修改預設組態有幾個原因。兩個範例原因如下：
+ 向服務的發行前版本或服務的本機部署提出請求。
+ 存取 SDK 中尚未建模的特定服務功能。

**警告**  
端點解析是進階 SDK 主題。如果您變更預設設定，可能會破壞程式碼。預設設定適用於生產環境中的大多數使用者。

自訂端點可以全域設定，以便用於所有服務請求，或者您可以為特定 設定自訂端點 AWS 服務。

您可以使用環境變數或共用 AWS `config`檔案中的設定來設定自訂端點。如需此方法的資訊，請參閱 *AWS SDKs和工具參考指南*中的[服務特定端點](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)。如需所有 共用`config`檔案設定和環境變數的完整清單 AWS 服務，請參閱[服務特定端點的識別符](https://docs.aws.amazon.com/sdkref/latest/guide/ss-endpoints-table.html)。

 或者，您也可以在程式碼中設定此自訂，如下列各節所示。

## 自訂組態
<a name="custom-configuration"></a>

您可以使用建置用戶端時可用的兩種方法來自訂服務用戶端的端點解析：

1. `endpoint_url(url: Into<String>)`

1. `endpoint_resolver(resolver: impl crate::config::endpoint::ResolveEndpoint + `static)`

您可以設定這兩個屬性。不過，您通常只提供一個。對於一般用途， `endpoint_url` 最常自訂。

### 設定端點 URL
<a name="set-endpoint-url"></a>

您可以為 設定值`endpoint_url`，以指出服務的「基礎」主機名稱。不過，此值不是最終值，因為它會以參數形式傳遞給用戶端的`ResolveEndpoint`執行個體。實作接著`ResolveEndpoint`可以檢查並可能修改該值，以判斷最終端點。

### 設定端點解析程式
<a name="set-endpoint-resolver"></a>

服務用戶端的`ResolveEndpoint`實作會決定開發套件用於任何指定請求的最終解析端點。服務用戶端會為每個請求呼叫 `resolve_endpoint`方法，並使用解析程式傳回[https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html)的值，而不會進一步變更。

下列範例示範為 Amazon S3 用戶端提供自訂端點解析程式實作，以解析每個階段的不同端點，例如預備和生產：

```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};

#[derive(Debug)]
struct StageResolver { stage: String }
impl ResolveEndpoint for StageResolver {
    fn resolve_endpoint(&self, params: &Params) -> EndpointFuture<'_> {
        let stage = &self.stage;
        EndpointFuture::ready(Ok(Endpoint::builder().url(format!("{stage}.myservice.com")).build()))
    }
}


let config = aws_config::defaults(BehaviorVersion::latest())
    .load()
    .await;

let resolver = StageResolver { stage: std::env::var("STAGE").unwrap() };

let s3_config = aws_sdk_s3::config::Builder::from(&config)
    .endpoint_resolver(resolver)
    .build();

let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```

**注意**  
端點解析程式和`ResolveEndpoint`延伸特徵是每個服務特有的，因此只能在服務用戶端組態上設定。另一方面，可以使用共用組態 （套用至衍生自它的所有服務） 或特定服務來設定端點 URL。

#### ResolveEndpoint 參數
<a name="resolveendpoint-parameters"></a>

`resolve_endpoint` 方法接受服務特定的參數，其中包含端點解析中使用的屬性。

每個服務都包含下列基本屬性：


| 名稱 | 類型 | Description | 
| --- | --- | --- | 
| region | String | 用戶端的 AWS 區域 | 
| endpoint | String | 的值集的字串表示法 endpointUrl | 
| use\$1fips | Boolean | 是否在用戶端的組態中啟用 FIPS 端點 | 
| use\$1dual\$1stack | Boolean | 是否在用戶端的組態中啟用雙堆疊端點 | 

AWS 服務 可以指定解析度所需的其他屬性。例如，Amazon S3 [端點參數](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/endpoint/struct.Params.html)包含儲存貯體名稱和數個 Amazon S3-specific功能設定。例如， `force_path_style` 屬性會判斷是否可以使用虛擬主機定址。

如果您實作自己的提供者，則不需要建構自己的端點參數執行個體。開發套件提供每個請求的屬性，並將其傳遞給您的 實作`resolve_endpoint`。

### 比較使用 `endpoint_url`與使用 `endpoint_resolver`
<a name="endpoint-url-or-endpoint-resolver"></a>

請務必了解下列兩個組態，一個使用 ，`endpoint_url`另一個使用 `endpoint_resolver`，不會產生具有同等端點解析行為的用戶端。

```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};

#[derive(Debug, Default)]
struct CustomResolver;
impl ResolveEndpoint for CustomResolver {
    fn resolve_endpoint(&self, _params: &Params) -> EndpointFuture<'_> {
        EndpointFuture::ready(Ok(Endpoint::builder().url("https://endpoint.example").build()))
    }
}

let config = aws_config::defaults(BehaviorVersion::latest())
    .load()
    .await;

// use endpoint url
aws_sdk_s3::config::Builder::from(&config)
    .endpoint_url("https://endpoint.example")
    .build();
    
// Use endpoint resolver
aws_sdk_s3::config::Builder::from(&config)
    .endpoint_resolver(CustomResolver::default())
    .build();
```

設定 的用戶端會`endpoint_url`指定傳遞至 （預設） 供應商*的基本* URL，此 URL 可做為端點解析的一部分進行修改。

設定 的用戶端會`endpoint_resolver`指定 Amazon S3 用戶端使用*的最終* URL。

## 範例
<a name="endpointsExamples"></a>

自訂端點通常用於測試。呼叫會路由到本機託管的模擬服務，而不是呼叫以雲端為基礎的服務。兩個這類選項為：
+ [DynamoDB local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) – Amazon DynamoDB 服務的本機版本。
+ [LocalStack](https://github.com/localstack/localstack) – 在本機電腦上容器中執行的雲端服務模擬器。

 下列範例說明指定自訂端點以使用這兩個測試選項的兩種不同方式。

### 直接在程式碼中使用 DynamoDB 本機
<a name="endpointsExamplesddb"></a>

如前幾節所述，您可以`endpoint_url`直接在程式碼中設定 ，以覆寫基本端點以指向本機 DynamoDB 伺服器。在您的程式碼中：

```
    let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
        .test_credentials()
        // DynamoDB run locally uses port 8000 by default.
        .endpoint_url("http://localhost:8000")
        .load()
        .await;
    let dynamodb_local_config = aws_sdk_dynamodb::config::Builder::from(&config).build();

    let client = aws_sdk_dynamodb::Client::from_conf(dynamodb_local_config);
```

[完整的範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb/src/bin/list-tables-local.rs)可在 GitHub 上取得。

### 使用 `config` 檔案使用 LocalStack
<a name="endpointsExamplesLs"></a>

您可以在共用 AWS `config`檔案中設定[服務特定的端點](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)。下列組態設定檔集`endpoint_url`可在連接埠 `localhost`上連線至 `4566`。如需 LocalStack 組態的詳細資訊，請參閱 [ LocalStack 文件網站上的透過端點 URL 存取](https://docs.localstack.cloud/references/network-troubleshooting/endpoint-url/) *LocalStack*。

```
[profile localstack]
region=us-east-1
endpoint_url = http://localhost:4566
```

軟體開發套件會取得共用`config`檔案中的變更，並在您使用`localstack`設定檔時將其套用至軟體開發套件用戶端。使用此方法，您的程式碼不需要包含任何端點的參考，而且看起來像：

```
    // set the environment variable `AWS_PROFILE=localstack` when running
    // the application to source `endpoint_url` and point the SDK at the
    // localstack instance
    let config = aws_config::defaults(BehaviorVersion::latest()).load().await;

    let s3_config = aws_sdk_s3::config::Builder::from(&config)
        .force_path_style(true)
        .build();

    let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```

[完整的範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/localstack)可在 GitHub 上取得。

# 在適用於 Rust 的 AWS SDK 中覆寫用戶端的單一操作組態
<a name="peroperation"></a>

[建立服務用戶端](config-code.md)之後，組態會變成不可變，並套用至所有後續操作。雖然目前無法修改組態，但每個操作都可以覆寫組態。

每個操作建置器都有可用來建立 `customize`的方法，`CustomizableOperation`讓您可以覆寫現有組態的個別複本。原始用戶端組態將保持不變。

下列範例顯示建立呼叫兩個操作的 Amazon S3 用戶端，第二個會覆寫以傳送至不同的操作 AWS 區域。所有 Amazon S3 的物件叫用都會使用 `us-east-1`區域，但明確覆寫 API 呼叫以使用修改的 時除外`us-west-2`。

```
use aws_config::{BehaviorVersion, Region};

let config = aws_config::defaults(BehaviorVersion::latest())
    .region("us-east-1")
    .load()
    .await;

let s3 = aws_sdk_s3::Client::new(&config);

// Request will be sent to "us-east-1"
s3.list_buckets()
    .send()
    .await?;

// Unset fields default to using the original config value
let modified = aws_sdk_s3::Config::builder()
    .region(Region::from_static("us-west-2"));

// Request will be sent to "us-west-2"
s3.list_buckets()
   // Creates a CustomizableOperation
    .customize()
    .config_override(modified)
    .send()
    .await?;
```

**注意**  
上述範例適用於 Amazon S3，但所有操作的概念都相同。某些操作在 上可能會有其他方法`CustomizeableOperation`。

如需使用 `customize`為單一操作新增攔截器的範例，請參閱 [僅特定操作的攔截器](interceptors.md#interceptors-registration-specific)。

# 在適用於 Rust 的 AWS SDK 中設定 HTTP 層級設定
<a name="http"></a>

 適用於 Rust 的 AWS SDK 提供內建 HTTP 功能，可供 AWS 服務 您在程式碼中建立的用戶端使用。

根據預設，適用於 Rust 的 開發套件會使用基於 `hyper`、 `rustls`和 的 HTTPS 用戶端`aws-lc-rs`。此用戶端應適用於大多數使用案例，無需其他組態。
+ [https://docs.rs/hyper/latest/hyper/](https://docs.rs/hyper/latest/hyper/) 是 Rust 的較低層級 HTTP 程式庫，可與 搭配使用 適用於 Rust 的 AWS SDK ，以進行 API 服務呼叫。
+ [https://github.com/rustls/rustls](https://github.com/rustls/rustls) 是以 Rust 編寫的現代 TLS 程式庫，具有密碼編譯提供者的內建選項。
+ [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc) 是一般用途的密碼編譯程式庫，包含 TLS 和常見應用程式所需的演算法。
+ [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) 是圍繞 Rust 中`aws-lc`程式庫的慣用包裝函式。

如果您想要選擇不同的 TLS 或密碼編譯提供者，`aws-smithy-http-client`則條板箱會提供一些額外的選項和組態。對於更進階的使用案例，建議您使用自己的 HTTP 用戶端實作或提交功能請求以供考量。

## 選擇替代的 TLS 提供者
<a name="tlsProviders"></a>

`aws-smithy-http-client` 木箱提供一些替代的 TLS 提供者。

提供下列供應商：

**`rustls` 取代為 `aws-lc`**  
使用 [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)進行密碼編譯[https://github.com/rustls/rustls](https://github.com/rustls/rustls)的 TLS 提供者。  
這是 SDK for Rust 的預設 HTTP 行為。如果您想要使用此選項，您不需要在程式碼中採取任何其他動作。

**`s2n-tls`**  
以 為基礎的 TLS 提供者[https://github.com/aws/s2n-tls](https://github.com/aws/s2n-tls)。

**`rustls` 取代為 `aws-lc-fips`**  
以 為基礎的 TLS 提供者[https://github.com/rustls/rustls](https://github.com/rustls/rustls)，使用符合 FIPS 的 版本[https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)進行密碼編譯

**`rustls` 取代為 `ring`**  
使用 [https://github.com/briansmith/ring](https://github.com/briansmith/ring)進行密碼編譯[https://github.com/rustls/rustls](https://github.com/rustls/rustls)的 TLS 提供者。

### 先決條件
<a name="prereqTls"></a>

使用 `aws-lc-rs`或 `s2n-tls`需要 C 編譯器 (Clang 或 GCC) 才能建置。對於某些平台，建置也可能需要 CMake。在任何平台上使用「光纖」功能建置 需要 CMake 和 Go。如需詳細資訊，請參閱 [AWS Libcrypto for Rust (`aws-lc-rs`) ](https://github.com/aws/aws-lc-rs/blob/main/aws-lc-rs/README.md)儲存庫和建置說明。

### 如何使用替代 TLS 提供者
<a name="s2nTls"></a>

`aws-smithy-http-client` 木箱提供額外的 TLS 選項。若要讓您的 AWS 服務 用戶端使用不同的 TLS 提供者，`http_client`請使用 條`aws_config`箱中的載入器覆寫 。HTTP 用戶端用於 AWS 服務 和 登入資料提供者。

下列範例示範如何使用 `s2n-tls` TLS 提供者。不過，類似的方法也適用於其他供應商。

若要編譯範例程式碼，請執行下列命令，將相依性新增至您的專案：

```
cargo add aws-smithy-http-client -F s2n-tls
```

範例程式碼：

```
use aws_smithy_http_client::{tls, Builder};

#[tokio::main]
async fn main() {
    let http_client = Builder::new()
        .tls_provider(tls::Provider::S2nTls)
        .build_https();

    let sdk_config = aws_config::defaults(
        aws_config::BehaviorVersion::latest()
    )
    .http_client(http_client)
    .load()
    .await;

    // create client(s) using sdk_config
    // e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```

## 啟用 FIPS 支援
<a name="fipsTls"></a>

`aws-smithy-http-client` 木箱提供啟用 FIPS 相容加密實作的選項。若要讓您的 AWS 服務 用戶端使用符合 FIPS 規範的提供者，`http_client`請使用 條`aws_config`箱中的載入器覆寫 。HTTP 用戶端用於 AWS 服務 和 登入資料提供者。

**注意**  
FIPS 支援需要您建置環境中的其他相依性。請參閱 `aws-lc` 木箱的[建置](https://github.com/aws/aws-lc/blob/main/BUILDING.md)說明。

若要編譯範例程式碼，請執行下列命令，將相依性新增至您的專案：

```
cargo add aws-smithy-http-client -F rustls-aws-lc-fips
```

下列範例程式碼啟用 FIPS 支援：

```
// file: main.rs
use aws_smithy_http_client::{
    tls::{self, rustls_provider::CryptoMode},
    Builder,
};

#[tokio::main]
async fn main() {
    let http_client = Builder::new()
        .tls_provider(tls::Provider::Rustls(CryptoMode::AwsLcFips))
        .build_https();

    let sdk_config = aws_config::defaults(
        aws_config::BehaviorVersion::latest()
    )
    .http_client(http_client)
    .load()
    .await;

    // create client(s) using sdk_config
    // e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```

## 排定後量子金鑰交換的優先順序
<a name="quantumTls"></a>

預設 TLS 提供者是以`rustls`使用 為基礎`aws-lc-rs`，支援`X25519MLKEM768`後量子金鑰交換演算法。若要讓 成為`X25519MLKEM768`最高優先順序的演算法，您需要將`rustls`套件新增至您的木箱，並啟用`prefer-post-quantum`功能旗標。否則，它是可用的，但不是最高優先順序。如需詳細資訊，請參閱 `rustls` [文件](https://docs.rs/rustls/0.23.23/rustls/manual/_05_defaults/index.html#about-the-post-quantum-secure-key-exchange-x25519mlkem768)。

**注意**  
這將成為未來版本的預設值。

## 覆寫 DNS 解析程式
<a name="overrideDns"></a>

 手動設定 HTTP 用戶端可以覆寫預設 DNS 解析程式。

若要編譯範例程式碼，請執行下列命令，將相依性新增至您的專案：

```
cargo add aws-smithy-http-client -F rustls-aws-lc
cargo add aws-smithy-runtime-api -F client
```

下列範例程式碼會覆寫 DNS 解析程式：

```
use aws_smithy_http_client::{
    tls::{self, rustls_provider::CryptoMode},
    Builder
};
use aws_smithy_runtime_api::client::dns::{DnsFuture, ResolveDns};
use std::net::{IpAddr, Ipv4Addr};

/// A DNS resolver that returns a static IP address (127.0.0.1)
#[derive(Debug, Clone)]
struct StaticResolver;

impl ResolveDns for StaticResolver {
    fn resolve_dns<'a>(&'a self, _name: &'a str) -> DnsFuture<'a> {
        DnsFuture::ready(Ok(vec![IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))]))
    }
}

#[tokio::main]
async fn main() {
    let http_client = Builder::new()
        .tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
        .build_with_resolver(StaticResolver);
    
    let sdk_config = aws_config::defaults(
        aws_config::BehaviorVersion::latest()
    )
    .http_client(http_client)
    .load()
    .await;
    
    // create client(s) using sdk_config
    // e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```

**注意**  
根據預設，Amazon Linux 2023 (AL2023) 不會在作業系統層級快取 DNS。

## 自訂根 CA 憑證
<a name="customizeCertificatesTls"></a>

根據預設，TLS 提供者會載入指定平台的系統原生根憑證。若要自訂此行為以載入自訂 CA 套件，您可以使用`TlsContext`自己的 來設定 `TrustStore`。

若要編譯範例程式碼，請執行下列命令，將相依性新增至您的專案：

```
cargo add aws-smithy-http-client -F rustls-aws-lc
```

下列範例使用 `rustls`搭配 ，`aws-lc`但適用於任何支援的 TLS 提供者：

```
use aws_smithy_http_client::{
    tls::{self, rustls_provider::CryptoMode},
    Builder
};
use std::fs;

/// read the PEM encoded root CA (bundle) and return a custom TLS context
fn tls_context_from_pem(filename: &str) -> tls::TlsContext {
    let pem_contents = fs::read(filename).unwrap();
    
    // Create a new empty trust store (this will not load platform native certificates)
    let trust_store = tls::TrustStore::empty()
        .with_pem_certificate(pem_contents.as_slice());
        
    tls::TlsContext::builder()
        .with_trust_store(trust_store)
        .build()
        .expect("valid TLS config")
}

#[tokio::main]
async fn main() {
    let http_client = Builder::new()
        .tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
        .tls_context(tls_context_from_pem("my-custom-ca.pem"))
        .build_https();
    
    let sdk_config = aws_config::defaults(
        aws_config::BehaviorVersion::latest()
    )
    .http_client(http_client)
    .load()
    .await;
    
    // create client(s) using sdk_config
    // e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```

# 在適用於 Rust 的 AWS SDK 中設定攔截器
<a name="interceptors"></a>

您可以使用攔截器來勾結 API 請求和回應的執行。攔截器是開放式機制，其中 SDK 會呼叫您寫入的程式碼，將行為注入請求/回應生命週期。如此一來，您就可以修改處理中的請求、偵錯請求處理、檢視錯誤等。

下列範例顯示簡單的攔截器，在輸入重試迴圈之前，會將額外的標頭新增至所有傳出請求：

```
use std::borrow::Cow;
use aws_smithy_runtime_api::client::interceptors::{
    Intercept,
    context::BeforeTransmitInterceptorContextMut,   
};
use aws_smithy_runtime_api::client::runtime_components::RuntimeComponents;
use aws_smithy_types::config_bag::ConfigBag;
use aws_smithy_runtime_api::box_error::BoxError;

#[derive(Debug)]
struct AddHeaderInterceptor {
    key: Cow<'static, str>,
    value: Cow<'static, str>,
}

impl AddHeaderInterceptor {
    fn new(key: &'static str, value: &'static str) -> Self {
        Self {
            key: Cow::Borrowed(key),
            value: Cow::Borrowed(value),
        }
    }
}

impl Intercept for AddHeaderInterceptor {
    fn name(&self) -> &'static str {
        "AddHeader"
    }

    fn modify_before_retry_loop(
        &self,
        context: &mut BeforeTransmitInterceptorContextMut<'_>,
        _runtime_components: &RuntimeComponents,
        _cfg: &mut ConfigBag,
    ) -> Result<(), BoxError> {
        let headers = context.request_mut().headers_mut();
        headers.insert(self.key.clone(), self.value.clone());

        Ok(())
    }
}
```

如需詳細資訊和可用的攔截器掛鉤，請參閱[攔截](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/interceptors/trait.Intercept.html)特徵。

## 攔截器註冊
<a name="interceptors-registration"></a>

您可以在建構服務用戶端或覆寫特定操作的組態時註冊攔截器。根據您希望攔截器套用到用戶端的所有操作，還是只套用特定操作， 中的註冊會有所不同。

### 服務用戶端上所有操作的攔截器
<a name="interceptors-registration-all"></a>

若要註冊整個用戶端的攔截器，請使用 `Builder` 模式新增攔截器。

```
let config = aws_config::defaults(BehaviorVersion::latest())
    .load()
    .await;
    
// All service operations invoked using 's3' will have the header added.
let s3_conf = aws_sdk_s3::config::Builder::from(&config)
    .interceptor(AddHeaderInterceptor::new("x-foo-version", "2.7"))
    .build();

let s3 = aws_sdk_s3::Client::from_conf(s3_conf);
```

### 僅特定操作的攔截器
<a name="interceptors-registration-specific"></a>

若要僅註冊單一操作的攔截器，請使用 `customize`擴充功能。您可以使用此方法覆寫每個操作層級的服務用戶端組態。如需可自訂操作的詳細資訊，請參閱 [在適用於 Rust 的 AWS SDK 中覆寫用戶端的單一操作組態](peroperation.md)。

```
// Only the list_buckets operation will have the header added.
s3.list_buckets()
    .customize()
    .interceptor(AddHeaderInterceptor::new("x-bar-version", "3.7"))
    .send()
    .await?;
```