# 为 API Gateway API 设置边缘优化的自定义域名 为边缘优化的 API 创建自定义域名时，API Gateway 会设置 CloudFront 分配和 DNS 记录，以将 API 域名映射到 CloudFront 分配域名。然后，对 API 的请求将通过映射的 CloudFront 分配路由到 API Gateway。此映射适用于针对要通过映射的 CloudFront 分配路由到 API Gateway 的自定义域名绑定的 API 请求。 ## 注意事项 以下是边缘优化的自定义域名的注意事项： + 要设置边缘优化的自定义域名或更新其证书，您必须有权更新 CloudFront 分配。 更新 CloudFront 分配需要以下权限： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] } ``` ------ + 您必须为您在美国东部（弗吉尼亚州北部）- `us-east-1` 区域的边缘优化自定义域名请求或导入证书。 + API Gateway 创建的 CloudFront 分配由与 API Gateway 关联的区域特定账户拥有。当跟踪操作以在 CloudTrail 中创建和更新此类 CloudFront 分配时，您必须使用此 API Gateway 账户 ID。有关更多信息，请参阅 [在 CloudTrail 中记录自定义域名的创建操作](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail)。 + API Gateway 在 CloudFront 分配上通过利用服务器名称指示 (SNI) 来支持边缘优化的自定义域名。有关在 CloudFront 分配上使用自定义域名的更多信息（包括所需证书格式和证书密钥最大长度），请参阅 *Amazon CloudFront 开发人员指南* 中的[使用备用域名和 HTTPS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html)。 + 边缘优化的自定义域名需要大约 40 分钟时间准备就绪。 + 创建边缘优化的自定义域名后，您必须创建 DNS 记录，以将自定义域名映射到 CloudFront 分配名称。 ## 创建边缘优化的自定义域名 以下过程说明了如何为 API 创建边缘优化的自定义域名。 ------ #### [ AWS 管理控制台 ] 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 从主导航窗格中选择**自定义域名**。 1. 选择**添加域列表**。 1. 对于**域名**，输入一个域名。 1. 对于**路由模式**，选择 **API\$1MAPPING\$1ONLY**。 1. 对于**端点类型**，选择**边缘优化**。 1. 选择最低 TLS 版本。 1. 选择 ACM 证书。 1. 选择**添加域列表**。 ------ #### [ REST API ] 1. 调用 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)，并指定自定义域名和 AWS Certificate Manager 中所存储证书的 ARN。 成功的 API 调用将返回 `201 Created` 响应，其中包含证书 ARN 以及负载中关联的 CloudFront 分配名称。 1. 请记下输出中显示的 CloudFront 分配域名。您在下一步中在 DNS 中设置自定义域的 A 记录别名目标时需要此域名。 有关此 REST API 调用的代码示例，请参阅 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)。 ------ 边缘优化的自定义域名需要大约 40 分钟时间准备就绪，但控制台会立即以 `distribution-id.cloudfront.net` 的形式显示关联的 CloudFront 分配域名以及证书 ARN。同时，您可以创建基本路径映射或路由规则，然后配置 DNS 记录别名，以便将自定义域名映射到关联的 CloudFront 分配域名。 ## 配置 API 的基本路径映射，将自定义域名作为主机名 因为您将路由模式设置为 `API_MAPPING_ONLY`，所以您可以使用基本路径映射来将单个自定义域名用作多个 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 阶段连接到 REST API 的自定义域名](rest-api-mappings.md)。 以下过程设置 API 映射，将您的自定义域名的路径映射到 API 阶段。 ------ #### [ AWS 管理控制台 ] 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 从 API Gateway 控制台的主导航窗格中选择**自定义域名**。 1. 选择自定义域名。 1. 选择**配置 API 映射**。 1. 选择**添加新映射**。 1. 指定映射的 **API**、**阶段**和**路径**（可选）。 1. 选择**保存**。 ------ #### [ REST API ] 在特定自定义域名上调用 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)，并指定 `basePath`、`restApiId` 和请求负载中的一个部署 `stage` 属性。 成功的 API 调用将返回 `201 Created` 响应。 有关 REST API 调用的代码示例，请参阅 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)。 ------ 为了更灵活地将流量路由到 API，可以将路由模式更改为 `ROUTING_RULE_ONLY` 或 `ROUTING_RULE_THEN_API_MAPPING`，然后创建路由规则。有关更多信息，请参阅 [在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。 ## 为边缘优化的自定义域名创建 DNS 记录 在开始创建边缘优化的自定义域名后，请设置 DNS 记录别名。 我们建议您使用 Route 53 为自定义域名创建 A 记录别名，同时指定 CloudFront 分配域名作为别名目标。这意味着，Route 53 可以路由自定义域名，即使是顶级域名也是如此。有关更多信息，请参阅 *Amazon Route 53 开发人员指南* 中的[在别名资源记录集和非别名资源记录集之间进行选择](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html)。 有关 Amazon Route 53 的说明，请参阅 *Amazon Route 53 开发人员指南*中的[使用域名将流量路由到 Amazon API Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。 ## 在 CloudTrail 中记录自定义域名的创建操作 启用 CloudTrail 以记录您的账户发出的 API Gateway 调用时，API Gateway 会在为 API 创建或更新自定义域名时记录关联的 CloudFront 分配更新。这些日志在 `us-east-1` 中提供。由于这些 CloudFront 分配归 API Gateway 拥有，因此每个报告的 CloudFront 分配都由以下特定于区域的 API Gateway 账户 ID 之一而不是 API 拥有者的账户 ID 来标识。 | **区域** | **账户 ID** | | --- | --- | | us-east-1 | 392220576650 | | us-east-2 | 718770453195 | | us-west-1 | 968246515281 | | us-west-2 | 109351309407 | | ca-central-1 | 796887884028 | | eu-west-1 | 631144002099 | | eu-west-2 | 544388816663 | | eu-west-3 | 061510835048 | | eu-central-1 | 474240146802 | | eu-central-2 | 166639821150 | | eu-north-1 | 394634713161 | | eu-south-1 | 753362059629 | | eu-south-2 | 359345898052 | | ap-northeast-1 | 969236854626 | | ap-northeast-2 | 020402002396 | | ap-northeast-3 | 360671645888 | | ap-southeast-1 | 195145609632 | | ap-southeast-2 | 798376113853 | | ap-southeast-3 | 652364314486 | | ap-southeast-4 | 849137399833 | | ap-south-1 | 507069717855 | | ap-south-2 | 644042651268 | | ap-east-1 | 174803364771 | | sa-east-1 | 287228555773 | | me-south-1 | 855739686837 | | me-central-1 | 614065512851 | ## 轮换 ACM 中导入的证书 ACM 会自动处理其所颁发证书的续订事宜。您不需要为自定义域名轮换 ACM 颁发的任何证书。CloudFront 会代表您处理这一事宜。 但是，如果您将证书导入到 ACM 并将其用于自定义域名，则您必须在证书到期前进行轮换。这包括导入域名的新第三方证书和将现有证书轮换为新证书。新导入的证书到期后，您需要重复上述过程。或者，您也可以请求 ACM 为域名颁发新证书并将现有证书轮换为 ACM 颁发的新证书。之后，您就可以让 ACM 和 CloudFront 自动为您处理证书轮换。要创建或导入新的 ACM 证书，请按照[在 ACM 中创建或导入 SSL/TLS 证书](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup)中的步骤操作。 以下过程说明了如何为域名轮换证书。 **注意** 轮换导入到 ACM 的证书大约需要 40 分钟。 ------ #### [ AWS 管理控制台 ] 1. 在 ACM 中请求或导入证书。 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 从 API Gateway 控制台的主导航窗格中选择**自定义域名**。 1. 选择边缘优化的自定义域名。 1. 对于**端点配置**，请选择**编辑**。 1. 从 **ACM 证书**下拉列表中选择证书。 1. 选择**保存更改**，开始轮换自定义域名的证书。 ------ #### [ REST API ] 调用 [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html) 操作，并为特定域名指定新 ACM 证书的 ARN。 ------ #### [ AWS CLI ] 以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 更新边缘优化域名的 ACM 证书。 ``` aws apigateway update-domain-name \ --domain-name edge.example.com \ --patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'" ``` 以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 更新区域域名的 ACM 证书。 ``` aws apigateway update-domain-name \ --domain-name regional.example.com \ --patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'" ``` ------ ## 使用基本路径映射时，通过自定义域名调用 API 如果使用的 URL 正确，则调用具有自定义域名的 API 与调用具有默认域名的 API 是一样的。 以下示例针对两个 API（`udxjef` 和 `qf3duz`），将它们在指定区域 (`us-east-1`) 的一组默认 URL 与其给定自定义域名 (`api.example.com`) 下的相应自定义 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，可以创建路由规则。有关更多信息，请参阅 [在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。 API Gateway 通过使用[服务器名称指示 (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) 来支持 API 的自定义域名。您可以使用浏览器或支持 SNI 的客户端库调用具有自定义域名的 API。 API Gateway 在 CloudFront 分配中强制实施 SNI。有关 CloudFront 如何使用自定义域名的信息，请参阅 [Amazon CloudFront 自定义 SSL](https://aws.amazon.com/cloudfront/custom-ssl-domains/)。