针对 API Gateway 中的 WebSocket API 自定义域名 - Amazon API Gateway
注意事项先决条件 通配符自定义域名自定义域名的后续步骤

针对 API Gateway 中的 WebSocket API 自定义域名

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

部署 API 后，您（和您的客户）可以使用以下格式的默认基本 URL 调用 API：

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

其中 api-id 由 API Gateway 生成，region 是 AWS 区域，stage 由您在部署 API 时指定。

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。

  • 仅支持区域自定义域名。

  • 对于最低 TLS 版本，仅支持 TLS 1.2。

  • 您必须创建或更新 DNS 提供程序的资源记录以映射到您的 API 端点。如果没有此类映射，针对自定义域名的 API 请求无法到达 API Gateway。

  • 您可以使用通配符证书，在不超过默认配额的情况下支持几乎无限数量的域名。有关更多信息，请参阅 通配符自定义域名。

先决条件

以下是自定义域名的先决条件。

注册域名

您必须拥有已注册的 Internet 域名，以便为 API 设置自定义域名。您可以使用 Amazon Route 53 或使用您选择的第三方域注册商注册互联网域名。自定义域名可以是注册的互联网域的子域或根域（也称为“机构根网域”）名称。

域名必须遵循 RFC 1035 规范，每个标签最多可以有 63 个八位字节，总共可以有 255 个八位字节。

自定义域名的证书

为 API 设置自定义域名之前，您必须先在 ACM 中准备好 SSL/TLS 证书。如果 ACM 在您要创建自定义域名的 AWS 区域中不可用，您必须将证书导入到该区域的 API Gateway。

要导入 SSL/TLS 证书，您必须针对自定义域名提供 PEM 格式的 SSL/TLS 证书文本、其私有密钥和证书链。

存储在 ACM 中的每个证书均由其 ARN 标识。如果拥有 ACM 颁发的证书，那么您就无需担心公开任何敏感的证书详细信息，如私有密钥。要针对域名使用 AWS 托管的证书，您只需参考其 ARN 即可。

如果您的应用程序使用证书固定（有时称为 SSL 固定）来固定 ACM 证书，则在 AWS 续订证书后，应用程序可能无法连接到您的域。有关更多信息，请参阅《AWS Certificate Manager 用户指南》中的证书固定问题。

通配符自定义域名

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

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

例如，通配符自定义域名 *.example.com 会生成子域，如 a.example.com、b.example.com 和 c.example.com，这些子域都会路由到同一个域。

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

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

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

注意

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

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

自定义域名的后续步骤

要为 HTTP API 设置自定义域名，您可以使用《API Gateway 开发人员指南》中的“REST API”部分的文档。

首先，为自定义域名指定一个证书。有关更多信息，请参阅 在 AWS Certificate Manager 中准备好证书。然后，创建一个区域性自定义域名。有关更多信息，请参阅 在 API Gateway 中设置区域自定义域名。