在 API Gateway 中设置区域自定义域名 - Amazon API Gateway

在 API Gateway 中设置区域自定义域名

使用区域自定义域名创建用户友好的 API 基本 URL。利用区域自定义域名,您可以将 HTTP 和 REST API 阶段映射到相同的自定义域名并使用双向 TLS 身份验证。

注意事项

以下是区域自定义域名的注意事项:

  • 您必须提供特定于区域的 ACM 证书。该证书必须与您的 API 位于同一区域。有关创建或上传自定义域名证书的更多信息,请参阅在 AWS Certificate Manager 中准备好证书

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

  • 创建区域自定义域名后,您必须创建 DNS 记录,以将该自定义域名指向区域域。这使绑定到自定义域名的流量可以路由到 API 的区域主机名。

    DNS 记录可以是 CNAME 记录或 A 别名记录。如果您使用 Route 53 作为 DNS 提供商,请创建 A 别名记录。如果您使用第三方 DNS 提供商,请使用 CNAME 记录。如果您使用 CNAME 记录并创建 API Gateway 接口 VPC 端点,同时在 VPC 端点上为私有 API 启用了私有 DNS,则您无法解析托管私有 API 的 VPC 中的自定义域名。

创建区域自定义域名

以下过程说明了如何创建区域自定义域名。完成该过程后,可以创建路由规则,以便将 API 的各阶段路由到自定义域名。

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

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

  3. 选择创建

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

  5. 对于路由模式,请选择仅限路由规则

    在这一路由模式下,只能使用路由规则将流量从自定义域名发送到 API。有关更多信息,请参阅 在 API Gateway 中通过自定义域名将流量发送到 API

  6. 对于最低 TLS 版本,选择一个版本。

  7. 端点配置下,对于 API 端点类型,选择区域性

  8. 选择 ACM 证书。证书必须与 API 位于同一区域。

  9. 选择创建

AWS CLI

使用以下 create-domain-name 命令创建自定义域名:

aws apigatewayv2 create-domain-name \ --domain-name 'regional.example.com' \ --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \ --routing-mode ROUTING_RULE_ONLY

输出将与以下内容类似:

{ "ApiMappingSelectionExpression": "$request.basepath", "DomainName": "regional.example.com", "DomainNameConfigurations": [ { "ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com", "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678", "DomainNameStatus": "AVAILABLE", "EndpointType": "REGIONAL", "HostedZoneId": "Z2OJLYMUO9EFXC", "SecurityPolicy": "TLS_1_2" } "RoutingMode": "ROUTING_RULE_ONLY" ] }

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

为区域自定义域名创建路由规则

创建自定义域名后,您可以配置如何将流量从自定义域名路由到 API。由于您将路由模式设置为 ROUTING_RULE_ONLY,因此,您使用路由规则将针对自定义域名的传入请求路由到 API。

在此示例中,您创建一条“捕获全部”规则,该规则将所有针对自定义域名的传入请求路由到 API 的一个阶段。还可以根据不同的标头和路径条件配置路由规则。有关更多信息,请参阅 将 API 阶段连接到 REST API 的自定义域名的路由规则

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

  2. 选择自定义域名。

  3. 路由详情选项卡上,选择添加路由规则

  4. 选择添加新条件以添加新条件。

  5. 遵守此规则,而不附加任何条件。这会将所有针对自定义域名的请求路由到目标 API 和目标阶段。

  6. 对于操作,使用下拉列表来选择目标 API 和目标阶段。

  7. 选择下一步

  8. 在优先级字段中,输入 100

    API Gateway 按优先级顺序(从最低值到最高值)评估规则。由于这是一条“捕获全部”规则,因此您使用高优先级,以便 API Gateway 可以匹配您先创建的任何其它规则。

  9. 选择创建路由规则

AWS CLI

以下 create-routing-rule 命令创建“捕获全部”路由规则:

aws apigatewayv2 create-routing-rule \ --domain-name 'regional.example.com' \ --priority 100 \ --conditions \ --actions '[{ "InvokeApi": { "ApiId": "a1b2c3", "Stage": "prod" } }]'

您可以随时更改路由模式并创建新规则。有关更多信息,请参阅 在 API Gateway 中通过自定义域名将流量发送到 API

为区域自定义域名创建 DNS 记录

创建自定义域名和基本路径映射后,您可以创建 DNS 记录,将自定义域名指向新创建的区域域名。

AWS Management Console

要使用 AWS Management Console,请遵循有关配置 Route 53 以将流量路由到 API Gateway 的 Route 53 文档。

AWS CLI

要配置 DNS 记录来将区域自定义域名映射到给定托管区 ID 的主机名,首先要创建一个 JSON 文件,其中包含用于为区域域名设置 DNS 记录的配置。

以下 setup-dns-record.json 显示了如何创建 DNS A 记录,以将区域自定义域名 (regional.example.com) 映射到在创建自定义域名时为其预配置的区域主机名 (d-numh1z56v6.execute-api.us-west-2.amazonaws.com)。DNSNameHostedZoneIdAliasTarget 属性可分别采用自定义域名的 regionalDomainNameregionalHostedZoneId 值。您也可以在 Amazon 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 } } } ] }

使用以下 change-resource-record-sets 命令为区域自定义域名创建 DNS 记录:

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

hosted-zone-id 替换为您账户中设置的 DNS 记录的 Route 53 托管区 ID。change-batch 参数值指向文件夹 (path/to/your) 中的 JSON 文件 (setup-dns-record.json)。