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

配置客户端终端节点

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

在构建服务客户端时，可以为 SDK 配置端点解析。端点解析的默认配置通常没问题，但是有几个原因可能会导致您修改默认配置。两个示例原因如下所示：

自定义配置

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

Set endpointUrl

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

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

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

Set endpointProvider

服务客户端的EndpointProvider实现决定了终端节点的最终解析。以下代码块中显示的EndpointProvider接口公开了该resolveEndpoint方法。

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

服务客户端为每个请求调用该resolveEndpoint方法。服务客户端使用提供者返回的Endpoint值，不做任何进一步的更改。

EndpointProvider 属性

该resolveEndpoint方法接受服务特定的EndpointParameters对象，该对象包含端点解析中使用的属性。

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

服务可以指定解析所需的其他属性。例如，Amazon S3 S3EndpointParameters包括存储桶名称以及几个特定于 Amazon S3 的功能设置。例如，forcePathStyle 属性决定是否可以使用虚拟主机寻址。

如果您实现了自己的提供程序，则无需构造自己的实例EndpointParameters。SDK 为每个请求提供属性并将其传递给您的 resolveEndpoint 实现。

endpointUrl 或 endpointProvider

重要的是要明白，以下两个语句不会生成具有相同端点解析行为的客户端：

// 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 的说明

Amazon S3 是一项复杂的服务，其许多功能都是通过自定义终端节点自定义建模的，例如存储桶虚拟托管。虚拟托管是 Amazon S3 的一项功能，其中存储桶名称会插入到主机名中。

因此，我们建议您不要替换 Amazon S3 服务客户端中的EndpointProvider实现。如果您需要扩展其解析行为，例如通过向本地开发堆栈发送请求以及其他端点注意事项，我们建议您封装默认实现。以下endpointProvider示例显示了此方法的示例实现。

示例

endpointUrl 示例

以下代码段显示了如何为 Amazon S3 客户端覆盖通用服务终端节点。

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

endpointProvider 示例

以下代码段展示了如何提供封装 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

以下示例程序演示了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) 
        // ...
    }
}