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

# 配置客户端终端节点
<a name="config-endpoint"></a>

当 适用于 Kotlin 的 AWS SDK 调用 a 时 AWS 服务，其第一步之一就是确定将请求路由到何处。此过程称为端点解析。

在构建服务客户端时，可以为 SDK 配置端点解析。端点解析的默认配置通常没问题，但是有几个原因可能会导致您修改默认配置。两个示例原因如下所示：
+ 向服务的预发行版本或服务的本地部署提出请求。
+ 访问尚未在 SDK 中建模的特定服务功能。

**警告**  
端点解析是一个高级 SDK 主题。如果您更改默认设置，则可能会破坏代码。默认设置应适用于生产环境中的大多数用户。

## 自定义配置
<a name="config-endpoint-custom-config"></a>

您可以使用构建客户端时可用的两个属性自定义服务客户端的端点解析：

1. `endpointUrl: Url`

1. `endpointProvider: EndpointProvider`

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

您可以为 `endpointUrl` 设置一个值来表示服务的“基本”主机名。但是，此值不是最终值，因为它是作为参数传递给客户端 `EndpointProvider` 实例的。然后，`EndpointProvider`实现可以检查并可能修改该值以确定最终端点。

例如，如果您为亚马逊简单存储服务 (Amazon S3) Simple Service 客户端指定`endpointUrl`值并执行`GetObject`操作，则默认终端节点提供程序实现会将存储桶名称注入主机名值。

实际上，用户将`endpointUrl`值设置为指向服务的开发或预览实例。

### Set `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`对象，该对象包含端点解析中使用的属性。

每项服务都包括以下基本属性。


****  

| Name | Type | 说明 | 
| --- | --- | --- | 
| region | 字符串 | 客户 AWS 所在的地区 | 
| endpoint | 字符串 | endpointUrl 的值集的字符串表示形式 | 
| useFips | 布尔值 | 是否在客户端配置中启用了 FIPS 端点 | 
| useDualStack | 布尔值 | 是否在客户端配置中启用了双栈端点 | 

服务可以指定解析所需的其他属性。例如，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 的功能设置。例如，`forcePathStyle` 属性决定是否可以使用虚拟主机寻址。

如果您实现了自己的提供程序，则无需构造自己的实例`EndpointParameters`。SDK 为每个请求提供属性并将其传递给您的 `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) 
        // ...
    }
}
```