针对 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 端点。默认 API 端点名称是随机生成的,难以重新调用,对用户不友好。api-id
.execute-api.region
.amazonaws.com
使用自定义域名,您可以设置 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
为您的自定义域名配置证书
为 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.com
、b.example.com
和 c.example.com
,这些子域都会路由到同一个域。
通配符自定义域名支持与 API Gateway 的标准自定义域名不同的配置。例如,在单个 Amazon 账户中,您可以对 *.example.com
和 a.example.com
进行不同的配置。
您可以使用 $context.domainName
和 $context.domainPrefix
上下文变量来确定客户端用于调用 API 的域名。要了解有关上下文变量的更多信息,请参阅 API Gateway 映射模板和访问日志记录变量引用。
要创建通配符自定义域名,您必须提供已使用 DNS 或电子邮件验证方法验证的由 ACM 颁发的证书。
注意
如果其他 Amazon 账户已经创建了与通配符自定义域名冲突的自定义域名,则无法创建通配符自定义域名。例如,如果账户 A 已经创建了 a.example.com
,则账户 B 无法创建通配符自定义域名 *.example.com
。
如果账户 A 和账户 B 共享拥有者,您可以联系 Amazon Support 中心
自定义域名的后续步骤
以下是自定义域名的后续步骤:
后续步骤
-
要了解如何设置 SSL/TLS 证书,请参阅在 Amazon Certificate Manager 中准备好证书。
-
要了解如何创建区域自定义域名,请参阅在 API Gateway 中设置区域自定义域名。
-
要了解如何创建边缘优化的自定义域名,请参阅为 API Gateway API 设置边缘优化的自定义域名。
-
要了解如何在区域自定义域名和边缘优化的自定义域名之间迁移,请参阅将自定义域名迁移至 API Gateway 中的其他 API 端点。
-
要了解如何将 API 阶段连接到自定义域名,请参阅将 API 阶段映射到 REST API 的自定义域名。
-
要了解如何为自定义域名选择安全策略,请参阅选择针对 API Gateway 中 REST API 自定义域的安全策略。
-
要了解如何关闭自定义域名的默认端点,请参阅禁用 REST API 的默认端点。
-
要了解如何使用 Route 53 运行状况检查从 API Gateway API 控制 DNS 故障转移,请参阅为 API Gateway API 配置针对 DNS 故障转移的自定义运行状况检查。
如果这是您第一次创建自定义域名,我们建议您首先在 Amazon Certificate Manager 中准备好证书,以便指定您的证书,然后再在 API Gateway 中设置区域自定义域名,以便创建区域自定义域名。