# 在 API Gateway 中设置区域自定义域名
使用区域自定义域名创建用户友好的 API 基本 URL。利用区域自定义域名，您可以将 HTTP 和 REST API 阶段映射到相同的自定义域名并使用双向 TLS 身份验证。
## 注意事项
以下是区域自定义域名的注意事项：
+ 您必须提供特定于区域的 ACM 证书。该证书必须与您的 API 位于同一区域。有关创建或上传自定义域名证书的更多信息，请参阅[在 AWS Certificate Manager 中准备好证书](how-to-specify-certificate-for-custom-domain-name.md)。
+ 在您创建（或迁移）包含 ACM 证书的区域自定义域名时，API Gateway 会在您的账户中创建一个服务相关角色。需要使用服务相关角色，才能将 ACM 证书附加到您的区域端点。该角色名为 **AWSServiceRoleForAPIGateway**，将对其附加 **APIGatewayServiceRolePolicy** 托管策略。有关使用服务相关角色的更多信息，请参阅[使用服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
+ 创建区域自定义域名后，您必须创建 DNS 记录，以将该自定义域名指向区域域。这使绑定到自定义域名的流量可以路由到 API 的区域主机名。
DNS 记录可以是 CNAME 记录或 A 别名记录。如果您使用 Route 53 作为 DNS 提供商，请创建 A 别名记录。如果您使用第三方 DNS 提供商，请使用 CNAME 记录。如果您使用 CNAME 记录并创建 API Gateway 接口 VPC 端点，同时在 VPC 端点上为私有 API 启用了私有 DNS，则您无法解析托管私有 API 的 VPC 中的自定义域名。
## 创建区域自定义域名
以下过程说明了如何创建区域自定义域名。完成该过程后，可以创建路由规则，以便将 API 的各阶段路由到自定义域名。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择**创建**。
1. 对于**域名**，输入一个域名。
1. 对于**路由模式**，请选择**仅限路由规则**。
在这一路由模式下，只能使用路由规则将流量从自定义域名发送到 API。有关更多信息，请参阅 [在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。
1. 对于**最低 TLS 版本**，选择一个版本。
1. 在**端点配置**下，对于 **API 端点类型**，选择**区域性**。
1. 选择 ACM 证书。证书必须与 API 位于同一区域。
1. 选择**创建**。
------
#### [ AWS CLI ]
使用以下 [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) 命令创建自定义域名：
```
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 的自定义域名的路由规则](rest-api-routing-rules.md)。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择自定义域名。
1. 在**路由详情**选项卡上，选择**添加路由规则**。
1. 选择**添加新条件**以添加新条件。
1. 遵守此规则，而不附加任何条件。这会将所有针对自定义域名的请求路由到目标 API 和目标阶段。
1. 对于**操作**，使用下拉列表来选择目标 API 和目标阶段。
1. 选择**下一步**。
1. 在优先级字段中，输入 **100**。
API Gateway 按优先级顺序（从最低值到最高值）评估规则。由于这是一条“捕获全部”规则，因此您使用高优先级，以便 API Gateway 可以匹配您先创建的任何其它规则。
1. 选择**创建路由规则**。
------
#### [ 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](rest-api-routing-mode.md)。
## 为区域自定义域名创建 DNS 记录
创建自定义域名和基本路径映射后，您可以创建 DNS 记录，将自定义域名指向新创建的区域域名。
------
#### [ AWS 管理控制台 ]
要使用 AWS 管理控制台，请遵循有关[配置 Route 53 以将流量路由到 API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html) 的 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`)。`DNSName` 的 `HostedZoneId` 和 `AliasTarget` 属性可分别采用自定义域名的 `regionalDomainName` 和 `regionalHostedZoneId` 值。您也可以在 [Amazon API Gateway 端点和配额](https://docs.aws.amazon.com/general/latest/gr/apigateway.html)中获取区域 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](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) 命令为区域自定义域名创建 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*)。
------