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

# 設定用戶端端點
<a name="config-endpoint"></a>

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

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

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

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

您可以使用建置用戶端時可用的兩個屬性來自訂服務用戶端的端點解析：

1. `endpointUrl: Url`

1. `endpointProvider: EndpointProvider`

### 設定 `endpointUrl`
<a name="config-endpoint-custom-config-endpointurl"></a>

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

例如，如果您指定 Amazon Simple Storage Service (Amazon S3) 用戶端`endpointUrl`的值並執行`GetObject`操作，預設端點提供者實作會將儲存貯體名稱注入主機名稱值。

實際上，使用者將 `endpointUrl`值設定為指向服務的開發或預覽執行個體。

### 設定 `endpointProvider`
<a name="config-endpoint-custom-config-endpointprovider"></a>

服務用戶端的`EndpointProvider`實作決定最終端點解析。下列程式碼區塊中顯示的`EndpointProvider`界面公開了 `resolveEndpoint`方法。

```
public fun interface EndpointProvider<T> {
    public suspend fun resolveEndpoint(params: T): Endpoint
}
```

服務用戶端會針對每個請求呼叫 `resolveEndpoint`方法。服務用戶端使用提供者傳回`Endpoint`的值，不會進一步變更。

#### `EndpointProvider` 屬性
<a name="config-endpoint-custom-config-endpointprovider-params"></a>

`resolveEndpoint` 方法接受服務特定的`EndpointParameters`物件，其中包含端點解析中使用的屬性。

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


****  

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

服務可以指定解析所需的其他屬性。例如，Amazon S3 [https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3.endpoints/-s3-endpoint-parameters/index.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3.endpoints/-s3-endpoint-parameters/index.html)包含儲存貯體名稱和數個 Amazon S3-specific功能設定。例如， `forcePathStyle` 屬性會判斷是否可以使用虛擬主機定址。

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

### `endpointUrl` 或 `endpointProvider`
<a name="config-endpoint-custom-config-which"></a>

請務必了解，下列兩個陳述式不會產生具有同等端點解析行為的用戶端：

```
// Use endpointUrl.
S3Client.fromEnvironment { 
    endpointUrl = Url.parse("https://endpoint.example")
}

// Use endpointProvider.
S3Client.fromEnvironment {
    endpointProvider = object : S3EndpointProvider {
        override suspend fun resolveEndpoint(params: S3EndpointParameters): Endpoint = Endpoint("https://endpoint.example")
    }
}
```

設定 `endpointUrl` 屬性的 陳述式會指定傳遞給 （預設） 提供者*的基本* URL，這可以修改為端點解析的一部分。

設定 的 陳述式會`endpointProvider`指定 `S3Client`使用*的最終* URL。

雖然您可以設定這兩個屬性，但在大多數需要自訂的情況下，您可以提供其中一個屬性。身為一般 SDK 使用者，您最常提供 `endpointUrl`值。

### 有關 Amazon S3 的備註
<a name="config-endpoint-custom-config-s3"></a>

Amazon S3 是一種複雜的服務，具有許多透過自訂端點自訂建模的功能，例如儲存貯體虛擬託管。虛擬託管是 Amazon S3 的一項功能，其中儲存貯體名稱會插入主機名稱。

因此，建議您不要取代 Amazon S3 服務用戶端中的`EndpointProvider`實作。如果您需要擴展其解決行為，或許透過傳送請求到具有其他端點考量的本機開發堆疊，我們建議您包裝預設實作。下列`endpointProvider`範例顯示此方法的範例實作。

## 範例
<a name="config-endpoint-examples"></a>

### `endpointUrl` 範例
<a name="config-endpoint-examples-endpointurl"></a>

下列程式碼片段顯示如何覆寫 Amazon S3 用戶端的一般服務端點。

```
val client = S3Client.fromEnvironment {
    endpointUrl = Url.parse("https://custom-s3-endpoint.local")
    // EndpointProvider is left as the default.
}
```

### `endpointProvider` 範例
<a name="config-endpoint-examples-endpointprovider"></a>

下列程式碼片段示範如何提供自訂端點提供者，以包裝 Amazon S3 的預設實作。

```
import aws.sdk.kotlin.services.s3.endpoints.DefaultS3EndpointProvider
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointParameters
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointProvider
import aws.smithy.kotlin.runtime.client.endpoints.Endpoint

public class CustomS3EndpointProvider : S3EndpointProvider {
    override suspend fun resolveEndpoint(params: S3EndpointParameters) =
        if (/* Input params indicate we must route another endpoint for whatever reason. */) {
            Endpoint(/* ... */)
        } else {
            // Fall back to the default resolution.
            DefaultS3EndpointProvider().resolveEndpoint(params)
        }
}
```

### `endpointUrl` 和 `endpointProvider`
<a name="config-endpoint-examples-both"></a>

下列範例程式示範 `endpointUrl`和 `endpointProvider`設定之間的互動。這是進階使用案例。

```
import aws.sdk.kotlin.services.s3.S3Client
import aws.sdk.kotlin.services.s3.endpoints.DefaultS3EndpointProvider
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointParameters
import aws.sdk.kotlin.services.s3.endpoints.S3EndpointProvider
import aws.smithy.kotlin.runtime.client.endpoints.Endpoint

fun main() = runBlocking {
    S3Client.fromEnvironment {
        endpointUrl = Url.parse("https://example.endpoint")
        endpointProvider = CustomS3EndpointProvider()
    }.use { s3 ->
        // ...
    }
}

class CustomS3EndpointProvider : S3EndpointProvider {
    override suspend fun resolveEndpoint(params: S3EndpointParameters) {
        // The resolved string value of the endpointUrl set in the client above is available here.
        println(params.endpoint) 
        // ...
    }
}
```