为 REST API 设置自定义域名 - Amazon API Gateway
注册域名边缘优化的自定义域名区域自定义域名通配符自定义域名自定义域名的证书

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

为 REST API 设置自定义域名

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

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

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

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

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

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

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

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

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

您可以选择 REST API 支持的最低 TLS 版本。对于 REST API，您可以选择 TLS 1.2 或 TLS 1.0。

注册域名

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

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

注意

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

边缘优化的自定义域名

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

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

注意

API Gateway 创建的 CloudFront 分配由与 API Gateway 关联的区域特定账户拥有。当跟踪操作以在 CloudWatch Logs 中创建和更新此类 CloudFront 分配时，您必须使用此 API Gateway 账户 ID。有关更多信息，请参阅 在 CloudTrail 中记录自定义域名的创建操作。

要设置边缘优化的自定义域名或更新其证书，您必须有权更新 CloudFront 分配。

要提供访问权限，请为您的用户、组或角色添加权限：

更新 CloudFront 分配需要以下权限。

{
    "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 区域（美国东部（弗吉尼亚北部））中的第三方证书颁发机构颁发的证书。

区域自定义域名

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

通配符自定义域名

使用通配符自定义域名，您可以在不超过默认配额的情况下支持几乎无限数量的域名。例如，您可以为每位客户提供自己的域名 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 中心请求例外。

自定义域名的证书

重要

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

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

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

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

主题