为 WebSocket API 设置自定义域名 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

为 WebSocket API 设置自定义域名

自定义域名 是您可以提供给 API 用户的更简单、更直观的 URL。

部署 API 后,您 (和您的客户) 可以使用以下格式的默认基本 URL 调用 API:

https://api-id.execute-api.region.amazonaws.com/stage

其中api-id,由 API Gateway 生成,region(Amazon 区域)由您在创建 API 时指定,由您在部署 API 时指定。stage

URL 的主机名部分(即 api-id.execute-api.region.amazonaws.com)是指 API 终端节点。默认 API 终端节点难于重新调用,对用户不友好。

使用自定义域名,您可以设置 API 的主机名,并选择基本路径(例如 myservice)以将备用 URL 映射到 API。例如,一个更为用户友好的 API 基本 URL 可以变成:

https://api.example.com/myservice
注意

WebSocket API 的自定义域名无法映射到 REST API 或 HTTP API。

对于 WebSocket API,支持区域自定义域名。

对于 WebSocket API,TLS 1.2 是唯一支持的 TLS 版本。

注册域名

您必须拥有已注册的 Internet 域名,以便为 API 设置自定义域名。如果需要,您可以使用 Amazon Route 53 或使用您选择的第三方域注册商注册互联网域。API 的自定义域名可以是已注册 Internet 域的子域或根域(也称为“顶级域”)的名称。

在 API Gateway 中创建自定义域名后,您必须创建或更新 DNS 提供商的资源记录以映射到 API 终端节点。如果没有此类映射,针对自定义域名的 API 请求无法到达 API Gateway。

区域自定义域名

为区域 API 创建自定义域名时,API Gateway 为 API 创建区域域名。您必须设置将自定义域名映射到区域域名的 DNS 记录。您还必须为自定义域名提供证书。

通配符自定义域名

使用通配符自定义域名,您可以在不超过默认配额的情况下支持几乎无限数量的域名。例如,您可以为每位客户提供自己的域名 customername.api.example.com

要创建通配符自定义域名,可以指定通配符 (*) 作为表示根域所有可能子域的自定义域的第一个子域。

例如,通配符自定义域名 *.example.com 会生成子域,如 a.example.comb.example.comc.example.com,这些子域都会路由到同一个域。

通配符自定义域名支持与 API Gateway 的标准自定义域名不同的配置。例如,在单个 Amazon 账户中,您可以a.example.com以不同的方式配置*.example.com和行为。

您可以使用 $context.domainName$context.domainPrefix 上下文变量来确定客户端用于调用 API 的域名。要了解有关上下文变量的更多信息,请参阅 API Gateway 映射模板和访问日志记录变量引用

要创建通配符自定义域名,您必须提供已使用 DNS 或电子邮件验证方法验证的由 ACM 颁发的证书。

注意

如果其他 Amazon 账户创建的自定义域名与通配符自定义域名冲突,则无法创建通配符自定义域名。例如,如果账户 A 已经创建了 a.example.com,则账户 B 无法创建通配符自定义域名 *.example.com

如果账户 A 和账户 B 共享拥有者,您可以联系 Amazon Support 中心请求例外。

自定义域名的证书

重要

您为您的自定义域名配置了证书。如果您的应用程序使用证书固定(有时称为 SSL 固定)来固定 ACM 证书,则在 Amazon 续订证书后,应用程序可能无法连接到您的域。有关更多信息,请参阅《Amazon Certificate Manager 用户指南》中的证书固定问题

要为支持 ACM 的区域中的自定义域名提供证书,您必须从 ACM 请求证书。要为不支持 ACM 的区域中的区域自定义域名提供证书,您必须在该区域中将证书导入到 API Gateway。

要导入 SSL/TLS 证书,您必须针对自定义域名提供 PEM 格式的 SSL/TLS 证书文本、其私有密钥和证书链。存储在 ACM 中的每个证书均由其 ARN 标识。要将 Amazon 托管证书用于域名,只需引用其 ARN 即可。

通过 ACM 可以轻松地为 API 设置和使用自定义域名。您可以为给定的域名创建证书(或导入证书),使用 ACM 提供的证书的 ARN 在 API Gateway 中设置域名,然后将自定义域名下的基本路径映射到 API 的已部署阶段。如果拥有 ACM 颁发的证书,那么您就无需担心公开任何敏感的证书详细信息,如私有密钥。

设置自定义域名

有关设置自定义域名的详细信息,请参阅在 中准备好证书Amazon Certificate Manager在 API Gateway 中设置区域自定义域名