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

为 API Gateway 中的区域 API 设置自定义域名

与边缘优化的 API 终端节点一样,您可为区域 API 终端节点创建自定义域名。要支持区域自定义域名,必须提供证书。如果使用 AWS Certificate Manager (ACM) 证书,此证书必须是特定于区域的。如果 ACM 在区域中可用,则必须提供特定于该区域的 ACM 证书。如果该区域不支持 ACM,则必须在创建区域自定义域名时将证书上传到该区域的 API Gateway。有关创建或上传自定义域名证书的更多信息,请参阅在 AWS Certificate Manager 中准备好证书

重要

对于 API Gateway 区域自定义域名,您必须在与 API 相同的区域中请求或导入证书。

在您创建(或迁移)包含 ACM 证书的区域自定义域名时,如果不存在服务相关角色,API Gateway 会在您的账户中创建一个这样的角色。需要使用服务相关角色,才能将 ACM 证书附加到您的区域终端节点。该角色名为 AWSServiceRoleForAPIGateway,将附加 APIGatewayServiceRolePolicy 托管策略。有关使用服务相关角色的更多信息,请参阅使用服务相关角色

重要

您必须创建将自定义域名指向区域域名的 DNS 记录。这使绑定到自定义域名的流量可以路由到 API 的区域主机名。DNS 记录可以是 CNAME 或 A 类型。

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

要使用 API Gateway 控制台设置区域自定义域名,请使用以下过程。

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

  1. 登录到 API Gateway 控制台并在主导航窗格中选择 Custom Domain Names (自定义域名)

  2. 选择 Custom Domain Names (自定义域名) 表上方的 +Create New Custom Domain Name (+创建新自定义域名)

  3. Domain Name (域名)New Custom Domain Name (新自定义域名) 中,键入自定义域名,例如 my-api.example.com

  4. Endpoint Configuration (终端节点配置) 选择 Regional (区域)

  5. ACM Certificate (ACM 证书) 下拉列表中选择证书。证书必须来自部署 API 的同一区域。

  6. 如果您已创建和部署了 API 来使用此自定义域名,请选择 Add mapping (添加映射),在自定义域名下的 Path (路径) 中键入基本路径,从 Destination (目标) 下的 API 下拉列表中选择 API,然后从 Stage (阶段) 下拉列表中选择阶段。要添加另一个基本路径映射,请重复该步骤。

  7. 选择 Save (保存)

  8. 按照 Route 53 文档中有关配置 Route 53 以将流量路由至 API Gateway 的说明操作。

使用 AWS CLI 设置区域自定义域名

要使用 AWS CLI 为区域 API 设置自定义域名,请使用以下过程。

  1. 调用 create-domain-name,并指定 REGIONAL 类型的自定义域名和区域证书的 ARN。

    aws apigateway create-domain-name \ --domain-name 'regional.example.com' \ --endpoint-configuration types=REGIONAL \ --regional-certificate-arn 'arn:aws:acm:us-west-2:123456789012:certificate/c19332f0-3be6-457f-a244-e03a423084e6'

    请注意,指定的证书来自 us-west-2 区域,在此示例中,我们假定底层 API 来自同一区域。

    如果成功,调用返回的结果类似于以下内容:

    { "certificateUploadDate": "2017-10-13T23:02:54Z", "domainName": "regional.example.com", "endpointConfiguration": { "types": "REGIONAL" }, "regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/c19332f0-3be6-457f-a244-e03a423084e6", "regionalDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com" }

    regionalDomainName 属性值返回区域 API 的主机名。您必须创建将您的自定义域名指向此区域域名的 DNS 记录。这使绑定到自定义域名的流量可以路由到该区域 API 的主机名。

  2. 创建将自定义域名与区域域名进行关联的 DNS 记录。这使绑定到自定义域名的请求可以路由到 API 的区域主机名。

  3. 添加基本路径映射,以在部署阶段 (例如 0qzs2sy7bh) 在指定的自定义域名 (例如 test) 下公开指定的 API (例如 regional.example.com)。

    aws apigateway create-base-path-mapping \ --domain-name 'regional.example.com' \ --base-path 'RegionalApiTest' \ --rest-api-id 0qzs2sy7bh \ --stage 'test'

    这样,在此阶段部署的使用 API 的自定义域名的基本 URL 会变为 https://regional.example.com/RegionalApiTest

  4. 配置 DNS 记录,以将区域自定义域名映射到给定的托管区域 ID 的主机名。首先创建一个 JSON 文件,其中包含为区域域名设置 DNS 记录的配置。以下示例显示了如何创建 DNS A 记录,以将区域自定义域名 (regional.example.com) 映射到在创建自定义域名时为其预配置的区域主机名 (d-numh1z56v6.execute-api.us-west-2.amazonaws.com)。DNSNameHostedZoneIdAliasTarget 属性可分别采用自定义域名的 regionalDomainNameregionalHostedZoneId 值。您也可以在 API Gateway 区域和终端节点中获取区域 Route 53 托管区域 ID。

    { "Changes": [ { "Action": "CREATE", "ResourceRecordSet": { "Name": "regional.example.com", "Type": "A", "AliasTarget": { "DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] }
  5. 运行以下 CLI 命令:

    aws route53 change-resource-record-sets \ --hosted-zone-id {your-hosted-zone-id} \ --change-batch file://path/to/your/setup-dns-record.json

    其中,{your-hosted-zone-id} 是您账户中的 DNS 记录集的 Route 53 托管区域 ID。change-batch 参数值指向文件夹 (path/to/your) 中的 JSON 文件 (setup-dns-record.json)。