Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 API Gateway 中为 API 设置自定义域名

注意

现在可以选择您的 API 支持的最低 TLS 版本。对于 REST API,您可以选择 TLS 1.2 或 TLS 1.0。对于 WebSocket API,您只能选择 TLS 1.2。

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

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

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

注意

自定义域可以与 REST API 或 Websocket API 相关联,但不能同时与二者相关联。

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

引用 API 终端节点的 URL 的主机名部分 (即,api-id.execute-api.region.amazonaws.com),可以为边缘优化或区域。默认 API 终端节点难于重新调用,对用户不友好。要为 API 用户提供更简单且更直观的 URL,您可以设置自定义域名 (例如,api.example.com) 作为 API 的主机名,并选择基本路径 (例如,myservice) 将备用 URL 映射到此 API。更为用户友好的 API 基本 URL 现在变成:

https://api.example.com/myservice

如果您没有在自定义域名下设置任何基本映射,生成的 API 的基本 URL 与自定义域相同 (例如,https://api.example.com)。 在这种情况下,自定义域名不能支持多个 API。

在您部署边缘优化的 API 时,API Gateway 设置 Amazon CloudFront 分配和 DNS 记录以将 API 域名映射到 CloudFront 分配域名。然后,对 API 的请求通过映射的 CloudFront 分配路由到 API Gateway。

在为边缘优化的 API 创建自定义域名时,API Gateway 设置 CloudFront 分配。但是您必须设置 DNS 记录以将自定义域名映射到 CloudFront 分配域名,以使针对自定义域名的 API 请求通过映射的 CloudFront 分配路由到 API Gateway。您还必须为自定义域名提供证书。

为区域 API 创建自定义域名时,API Gateway 为 API 创建区域域名。您必须设置 DNS 记录以将自定义域名映射到区域域名,以使针对自定义域名的 API 请求通过映射的 API 终端节点路由到 API Gateway。您还必须为自定义域名提供证书。

注意

API Gateway 创建的 CloudFront 分配由附属于 API Gateway 的特定区域账户所有。在 CloudWatch 日志中跟踪此类 CloudFront 分配的创建和更新操作时,您必须使用 API Gateway 账户 ID。有关更多信息,请参阅 在 CloudTrail 中记录自定义域名的创建操作

要设置边缘优化的自定义域名或更新其证书,您必须有权更新 CloudFront 分配。为此,您可以为账户中的 IAM 用户、组或角色附加以下 IAM 策略声明:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] }

API Gateway 在 CloudFront 分配上通过利用服务器名称指示 (SNI) 来支持边缘优化的自定义域名。有关在 CloudFront 分配上使用自定义域名的更多信息,其中包括所需证书格式和证书密钥最大长度,请参阅 Amazon CloudFront 开发人员指南 中的使用备用域名和 HTTPS

要设置自定义域名作为 API 的主机名,API 所有者必须针对自定义域名提供 SSL/TLS 证书。

要为边缘优化的自定义域名提供此证书,您可以请求 AWS Certificate Manager (ACM) 在 ACM 中生成新证书,或向 ACM 导入由 us-east-1 区域(弗吉尼亚北部)中的第三方证书颁发机构颁发的证书。

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

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

借助 ACM,您可以简单直接地为 API 设置和使用自定义域名:在 ACM 中为指定域名创建或导入证书、使用 ACM 提供的证书 ARN 在 API Gateway 中设置域名,并将自定义域名下的基本路径映射到已部署的 API 阶段。如果佣有 ACM 颁发的证书,那么您就无需担心公开任何敏感的证书详细信息,如私有密钥。

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

在 API Gateway 中创建自定义域名后,您必须创建或更新域名服务 (DNS) 提供程序的资源记录,以将边缘优化的自定义域名映射到其 CloudFront 分配域名,或者将区域自定义域名映射到区域 API 终端节点。如果没有此类映射,针对自定义域名的 API 请求无法到达 API Gateway。

注意

边缘优化的自定义域名在特定区域中创建,并由特定 AWS 账户拥有。在区域或 AWS 账户之间移动此类自定义域名时,需要删除现有 CloudFront 分配并创建新的分配。该过程可能需要大约 30 分钟,然后新的自定义域名才可用。有关更多信息,请参阅更新 CloudFront 分配

以下页面介绍了如何使用 ACM 为自定义域名创建 SSL/TLS 证书、如何为 API 设置自定义域名、如何将特定 API 与自定义域名下的基本路径关联,以及如何续订(也称为“轮换”)已针对自定义域名导入 ACM 中的到期证书。