创建边缘优化的自定义域名 - Amazon API Gateway
为 API Gateway API 设置边缘优化自定义域名在 CloudTrail 中记录自定义域名的创建操作配置 API 的基本路径映射，将自定义域名作为主机名轮换 ACM 中导入的证书调用具有自定义域名的 API

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

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

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

以下过程介绍了如何使用 API Gateway 控制台为 API 创建自定义域名。

使用 API Gateway 控制台创建自定义域名

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

  2. 从主导航窗格中选择 Custom domain names (自定义域名)。

  3. 选择创建。

  4. 对于 Domain name (域名)，输入一个域名。

  5. 在“Configuration (配置)”下，选择 Edge-optimized (边缘优化)。

  6. 选择最低 TLS 版本。

  7. 选择 ACM 证书。

    注意

    要将 ACM 证书与 API Gateway 边缘优化的自定义域名结合使用，您必须在 us-east-1 区域（美国东部（弗吉尼亚北部））中请求或导入证书。

  8. 选择创建域名。

  9. 创建自定义域名后，控制台将显示关联的 CloudFront 分配域名（形式为 distribution-id.cloudfront.net）以及证书 ARN。请记下输出中显示的 CloudFront 分配域名。您在下一步设置自定义域的 CNAME 值或 DNS 中的 A 记录别名目标时会需要此域名。

    注意

    新创建的自定义域名需要大约 40 分钟才能就绪。同时，您可以配置 DNS 记录别名以将自定义域名映射到关联的 CloudFront 分配域名，并在自定义域名初始化的同时设置自定义域名的基本路径映射。

  10. 接下来，您可以使用 DNS 提供商配置 DNS 记录，以将自定义域名映射到关联的 CloudFront 分配。有关 Amazon Route 53 的说明，请参阅 Amazon Route 53 开发人员指南中的使用域名将流量路由到 Amazon API Gateway API。

    对于大多数 DNS 提供程序，将自定义域名添加到托管区域作为 CNAME 资源记录集。CNAME 记录名称指定您之前在 Domain Name (域名) 中输入的自定义域名（如 api.example.com）。CNAME 记录值指定 CloudFront 分配的域名。但是，如果自定义域是顶级域 (例如，是 example.com 而非 api.example.com)，则无法使用 CNAME 记录。顶级域通常还称为组织的根域。对于顶级域，您需要使用 A 记录别名 (如果受 DNS 提供程序支持)。

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

    使用 A 记录别名还不需要公开底层 CloudFront 分配域名，因为域名映射仅发生在 Route 53 中。出于这些原因，我们建议您尽可能使用 Route 53 A 记录别名。

除了使用 API Gateway 控制台之外，您还可以使用 API Gateway REST API、AWS CLI 或某种AWS开发工具包为 API 设置自定义域名。例如，以下过程概述了使用 REST API 调用执行此操作的步骤。

使用 API Gateway REST API 设置自定义域名

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

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

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

  3. 按照上述过程设置 A 记录别名以将自定义域名映射到 CloudFront 分配名称。

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

在 CloudTrail 中记录自定义域名的创建操作

启用 CloudTrail 以记录您的账户发出的 API Gateway 调用时，API Gateway 会在为 API 创建或更新自定义域名时记录关联的 CloudFront 分配更新。由于这些 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

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

您可以使用一个自定义域名作为多个 API 的主机名。您可以通过在自定义域名上配置基本路径映射来实现这一目的。借助基本路径映射，可通过自定义域名和关联的基本路径访问自定义域下的 API。

例如，如果您创建了一个名为 PetStore 的 API 和一个名为 PetShop 的 API 并在 API Gateway 中设置了一个自定义域名 api.example.com，则您可以将 PetStore API 的 URL 设置为 https://api.example.com 或 https://api.example.com/myPetStore。PetStore API 与自定义域名 myPetStore 下的空字符串或 api.example.com 基本路径关联。同样，您可以为 yourPetShop API 分配 PetShop 基本路径。然后，https://api.example.com/yourPetShop 的 URL 就成了 PetShop API 的根 URL。

在为 API 设置基本路径之前，请先完成 中的步骤为 API Gateway API 设置边缘优化自定义域名

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

使用 API Gateway 控制台创建 API 映射名称

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

  2. 选择自定义域名。

  3. 选择 Configure API mappings (配置 API 映射)。

  4. 选择 Add new mapping (添加新映射)。

  5. 指定映射的 API、Stage (阶段) 和 Path (路径)（可选）。

  6. 选择 Save。

此外，您还可以调用 API Gateway REST API、AWS CLI 或一个AWS开发工具包来设置 API（自定义域名作为其主机名）的基本路径映射。例如，以下过程概述了使用 REST API 调用执行此操作的步骤。

使用 API Gateway REST API 设置 API 的基本路径映射

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

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

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

轮换 ACM 中导入的证书

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

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

要为域名轮换证书，您可以使用 API Gateway 控制台、API Gateway REST API、AWS CLI 或某种AWS开发工具包。

使用 API Gateway 控制台轮换 ACM 中导入的到期证书

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

  2. 回到 API Gateway 控制台。

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

  4. 选择自定义域名。

  5. 选择 Edit。

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

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

    注意

    该过程大约需要 40 分钟才能完成。轮换完成后，您可以选择 ACM 证书旁边的双向箭头图标回滚到原始证书。

为了说明如何以编程方式轮换自定义域名的导入证书，我们概括了使用 API Gateway REST API 轮换证书的步骤。

使用 API Gateway REST API 轮换导入的证书

调用具有自定义域名的 API

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

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

具有默认域名和自定义域名的 API 的根 URL
API ID 阶段 默认 URL 基本路径 自定义 URL
udxjef pro https://udxjef.execute-api.us-east-1.amazonaws.com/pro /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。