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

如何创建边缘优化自定义域名

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

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

使用 API Gateway 控制台设置自定义域名

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. 从主导航窗格中选择 Custom Domain Names (自定义域名)

  3. 接下来选择 Create Custom Domain Name (创建自定义域名)

  4. New Custom Domain Name (新的自定义域名) 下:

    1. 对于 API 协议,选择 HTTP

    2. Domain Name (域名) 下的 Domain Name (域名) 中,键入自定义域名,例如 my-api.example.com

      注意

      请勿为您的自定义域名使用通配符(即 *)。即使 API Gateway 控制台(或 AWS CLI)接受通配符且可以将其映射到一个 CloudFront 分配,API Gateway 却不支持。但是,您可以使用通配符证书。

    3. Security Policy (安全策略) 中,选择所需的最低传输层安全性 (TLS) 版本。

    4. Endpoint Configuration (终端节点配置) 中,选择 Edge optimized (边缘已优化)

    5. ACM Certificate (ACM 证书) 列表中选择证书。

      注意

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

    6. Base Path Mappings (基本路径映射) 下选择 Add mapping (添加映射),以为指定阶段中已部署的 API(从 Destination (目标) 下拉列表中选择)设置基本路径(Path (路径))。 此外,您还可以在创建自定义域名后设置基本路径映射。有关更多信息,请参阅 配置其中自定义域名作为主机名的 API 的基本路径映射

    7. 选择 Save (保存)

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

    注意

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

  6. 在此步骤中,我们使用 Amazon Route 53 作为示例 DNS 提供程序来显示如何为 Internet 域设置 A 记录别名以将自定义域名映射到关联的 CloudFront 分配名称。相关说明也适用于其他 DNS 提供程序。

    1. 登录到 Route 53 控制台。

    2. 为自定义域 (如 A-IPv4 address) 创建 api.example.com 记录集。A 记录将自定义域名映射到 IP4 地址。

    3. 别名选择,在 Alias Target (别名目标)中键入 CloudFront 域名(如 d3boq9ikothtgw.cloudfront.net),然后选择 创建。此处,A 记录别名会将自定义域名映射到本身映射到 IP4 地址的指定 CloudFront 域名。

      
                                    在 API Gateway 中为 API 的自定义域名设置 DNS 记录别名

    提示

    Alias Hosted Zone ID (别名托管区域 ID) 标识的是指定 Alias Target (别名目标) 的托管区域。Route 53 控制台在您为 Alias Target (别名目标)输入有效的域名时会自动填入值。要在不使用 Route 53 控制台的情况下(如使用 AWS CLI)创建 A 记录别名,您必须指定所需的托管区域 ID。对于任何 CloudFront 分配域名,托管区域 ID 值始终为 Z2FDTNDATAQYW2,如 CloudFront 的 AWS 区域和终端节点中所述。

    对于大多数 DNS 提供程序,将自定义域名添加到托管区域作为 CNAME 资源记录集。CNAME 记录名称指定您之前在域名中键入的自定义域名(如 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. 按照上述过程中的步骤 6 设置 A 记录别名以将自定义域名映射到 CloudFront 分配名称。

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

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

如果为记录您账户所执行的 API Gateway 调用而启用了 CloudTrail,那么在您为 API 创建或更新自定义域名时,API Gateway 会记录关联的 CloudFront 分配更新。由于这些 CloudFront 分配归 API Gateway 所有,每个报告的 CloudFront 分配均由以下任一特定于区域的 API Gateway 账户 ID 而非 API 所有者的账户 ID 标识。

与自定义域名相关联的 CloudFront 分配的特定区域 API Gateway 账户 ID

区域 账户 ID
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
eu-west-1 631144002099
eu-west-2 544388816663
eu-central-1 474240146802
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-southeast-1 195145609632
ap-southeast-2 798376113853

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

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

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

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

使用 API Gateway 控制台为 API 映射设置基本路径

  1. 从您账户下的可用 Custom Domain Names (自定义域名) 列表中选择自定义域名。

  2. 选择 Show Base Path Mappings (显示基本路径映射)编辑

  3. 选择 Add mapping (添加映射)

  4. (可选)为路径键入基本路径名称,从目标选择 API,然后选择一个阶段。

    注意

    目标列表显示了您的账户下已部署的 API。

  5. 选择保存,完成 API 的基本路径映射的设置。

注意

要在映射创建后将其删除,请在要删除的映射的旁边选择垃圾桶图标。

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

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

  • 在特定自定义域名上调用 basepathmapping:create,并指定 basePathrestApiId 和请求负载中的个一个部署 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 控制台主导航窗格中选择 Custom Domain Names (自定义域名)

  4. Custom Domain Names (自定义域名) 窗格下,选择您所选的自定义域名。

  5. 选择 Edit

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

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

    注意

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

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

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

调用具有自定义域名的 API

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

以下示例就两个 API (udxjefqf3duz),将它们在特定区域 (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