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

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

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

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

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

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

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

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

https://api.example.com/myservice

注意事项

以下注意事项可能会影响您对自定义域名的使用。

  • 私有 API不支持自定义域名。

  • 您可以禁用 API 的默认端点。客户端仍然可以连接到您的默认端点,但它们会收到 403 Forbidden 状态码。

  • 区域自定义域名可以与 REST API 和 HTTP API 相关联。您可以使用 API Gateway 版本 2 API 为 REST API 创建和管理区域自定义域名。

  • 自定义域名跨所有 Amazon 账户在一个区域内必须是唯一的。

  • 您可以在边缘优化和区域终端节点之间迁移自定义域名。

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

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

  • 您可以为自定义域名选择安全策略。有关更多信息,请参阅 选择针对 API Gateway 中 REST API 自定义域的安全策略

  • 要配置具有多个级别的 API 映射,您必须使用区域自定义域名并使用 TLS 1.2 安全策略。

先决条件

以下是创建自定义域名的先决条件:

注册域名

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

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

为您的自定义域名配置证书

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

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

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

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

通配符自定义域名

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

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

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

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

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

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

注意

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

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

自定义域名的后续步骤

以下是自定义域名的后续步骤:

后续步骤

如果这是您第一次创建自定义域名,我们建议您首先在 Amazon Certificate Manager 中准备好证书,以便指定您的证书,然后再在 API Gateway 中设置区域自定义域名,以便创建区域自定义域名。