为 API Gateway API 设置边缘优化的自定义域名 - Amazon API Gateway
注意事项创建边缘优化的自定义域名为边缘优化的自定义域名创建 DNS 记录配置 API 的基本路径映射，将自定义域名作为主机名轮换 ACM 中导入的证书调用具有自定义域名的 API
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

为 API Gateway API 设置边缘优化的自定义域名

为边缘优化的 API 创建自定义域名时，API Gateway 会设置 CloudFront 分配和 DNS 记录，以将 API 域名映射到 CloudFront 分配域名。然后，对 API 的请求将通过映射的 CloudFront 分配路由到 API Gateway。此映射适用于针对要通过映射的 CloudFront 分配路由到 API Gateway 的自定义域名绑定的 API 请求。

注意事项

以下是边缘优化的自定义域名的注意事项。

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

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

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

  • 您必须为您在美国东部（弗吉尼亚州北部）- us-east-1 区域的边缘优化自定义域名请求或导入证书。

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

  • 边缘优化的自定义域名需要大约 40 分钟时间准备就绪。

  • 创建边缘优化的自定义域名后，您必须创建 DNS 记录，以将自定义域名映射到 CloudFront 分配名称。

创建边缘优化的自定义域名

以下过程说明了如何为 API 创建边缘优化的自定义域名。

Amazon Web Services Management Console

  1. 通过以下网址登录到 Amazon API Gateway 控制台：https://console.aws.amazon.com/apigateway。

  2. 从主导航窗格中选择自定义域名。

  3. 选择创建。

  4. 对于域名，输入一个域名。

  5. 对于最低 TLS 版本，选择一个版本。

  6. 在端点配置下，对于 API 端点类型，选择边缘优化。

  7. 对于 ACM 证书，选择一个 ACM 证书。

  8. 选择创建域名。

REST API

  1. 调用 domainname:create，并指定自定义域名和 Amazon Certificate Manager 中所存储证书的 ARN。

    成功的 API 调用将返回 201 Created 响应，其中包含证书 ARN 以及负载中关联的 CloudFront 分配名称。

  2. 请记下输出中显示的 CloudFront 分配域名。您在下一步设置自定义域的 CNAME 值或 DNS 中的 A 记录别名目标时会需要此域名。

有关此 REST API 调用的代码示例，请参阅 domainname:create。

边缘优化的自定义域名需要大约 40 分钟时间准备就绪，但控制台会立即以 distribution-id.cloudfront.net 的形式显示关联的 CloudFront 分配域名以及证书 ARN。同时，您可以继续下一步，即配置 DNS 记录别名以将自定义域名映射到关联的 CloudFront 分配域名。

为边缘优化的自定义域名创建 DNS 记录

在开始创建边缘优化的自定义域名后，请设置 DNS 记录别名。

我们建议您使用 Route 53 为自定义域名创建 A 记录别名，同时指定 CloudFront 分配域名作为别名目标。这意味着，Route 53 可以路由自定义域名，即使是顶级域名也是如此。有关更多信息，请参阅 Amazon Route 53 开发人员指南 中的在别名资源记录集和非别名资源记录集之间进行选择。

您也可以将自定义域作为 CNAME 资源记录集添加到托管区域。CNAME 记录名称指定您之前在域名中输入的自定义域名（如 api.example.com）。CNAME 记录值指定 CloudFront 分配的域名。

但是，如果自定义域是顶级域 (例如，是 example.com 而非 api.example.com)，则无法使用 CNAME 记录。顶级域通常还称为组织的根域。对于顶级域，您需要使用 A 记录别名 (如果受 DNS 提供程序支持)。

有关 Amazon Route 53 的说明，请参阅 Amazon Route 53 开发人员指南中的使用域名将流量路由到 Amazon API Gateway API。

配置 API 的基本路径映射，将自定义域名作为主机名

您可以利用基本路径映射将一个自定义域名作为多个 API 的主机名。这样，您就可以通过自定义域名和关联基本路径的组合访问 API。

例如，如果您在 API Gateway 中创建了一个名为 PetStore 的 API 和另一个名为 Dogs 的 API，然后设置了一个自定义域名 api.example.com，则可以将 PetStore API 的 URL 设置为 https://api.example.com。

这会将 PetStore API 与空字符串的基本路径相关联。如果您将 PetStore API 的 URL 设置为 https://api.example.com/PetStore，系统会将 PetStore API 与 PetStore 基本路径相关联。您可以为 MyDogList API 分配 Dogs 基本路径。然后，https://api.example.com/MyDogList 的 URL 就成了 Dogs API 的根 URL。

要在多个级别上配置 API 映射，您只能使用区域自定义域名。不支持边缘优化的自定义域名。有关更多信息，请参阅将 API 阶段映射到自定义域名。

以下过程设置 API 映射，将您的自定义域名的路径映射到 API 阶段。

Amazon Web Services Management Console

  1. 通过以下网址登录到 Amazon API Gateway 控制台：https://console.aws.amazon.com/apigateway。

  2. 从 API Gateway 控制台的主导航窗格中选择自定义域名。

  3. 选择自定义域名。

  4. 选择配置 API 映射。

  5. 选择添加新映射。

  6. 指定映射的 API、阶段和路径（可选）。

  7. 选择保存。

REST API

在特定自定义域名上调用 basepathmapping:create，并指定 basePath、restApiId 和请求负载中的一个部署 stage 属性。

成功的 API 调用将返回 201 Created 响应。

有关 REST API 调用的代码示例，请参阅 basepathmapping:create。

轮换 ACM 中导入的证书

ACM 会自动处理其所颁发证书的续订事宜。您不需要为自定义域名轮换 ACM 颁发的任何证书。CloudFront 会代表您处理这一事宜。

但是，如果您将证书导入到 ACM 并将其用于自定义域名，则您必须在证书到期前进行轮换。这包括导入域名的新第三方证书和将现有证书轮换为新证书。新导入的证书到期后，您需要重复上述过程。或者，您也可以请求 ACM 为域名颁发新证书并将现有证书轮换为 ACM 颁发的新证书。之后，您就可以让 ACM 和 CloudFront 自动为您处理证书轮换。要创建或导入新的 ACM 证书，请按照在 ACM 中创建或导入 SSL/TLS 证书中的步骤操作。

以下过程说明了如何为域名轮换证书。

注意

轮换导入到 ACM 的证书大约需要 40 分钟。

Amazon Web Services Management Console

  1. 在 ACM 中请求或导入证书。

  2. 通过以下网址登录到 Amazon API Gateway 控制台：https://console.aws.amazon.com/apigateway。

  3. 从 API Gateway 控制台的主导航窗格中选择自定义域名。

  4. 选择自定义域名。

  5. 选择编辑。

  6. 从 ACM 证书下拉列表中选择所需证书。

  7. 选择保存，开始轮换自定义域名的证书。

  8. 轮换完成后，您可以选择 ACM 证书旁边的双向箭头图标回滚到原始证书。

REST API

调用 domainname:update 操作，并为特定域名指定新 ACM 证书的 ARN。

调用具有自定义域名的 API

如果使用的 URL 正确，则调用具有自定义域名的 API 与调用具有默认域名的 API 是一样的。

以下示例针对两个 API（udxjef 和 qf3duz），将它们在指定区域 (us-east-1) 的一组默认 URL 与其给定自定义域名 (api.example.com) 下的相应自定义 URL 进行了对比。

具有默认域名和自定义域名的 API 的根 URL
API ID 阶段 默认 URL 基本路径 自定义 URL
udxjef prod https://udxjef.execute-api.us-east-1.amazonaws.com/prod /petstore https://api.example.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://api.example.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://api.example.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://api.example.com/bookstand

API Gateway 通过使用服务器名称指示 (SNI) 来支持 API 的自定义域名。您可以使用浏览器或支持 SNI 的客户端库调用具有自定义域名的 API。

API Gateway 在 CloudFront 分配中强制实施 SNI。有关 CloudFront 如何使用自定义域名的信息，请参阅 Amazon CloudFront 自定义 SSL。