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

# 在 中設定用戶端端點 適用於 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 上取得。