# API Gateway 中公共 REST API 的自定义域名
*自定义域名* 是您可以提供给 API 用户的更简单、更直观的 URL。
部署 API 后，您（和您的客户）可以使用以下格式的默认基本 URL 调用 API：
```
https://api-id.execute-api.region.amazonaws.com/stage
```
其中 *api-id* 由 API Gateway 生成，*region* 是 AWS 区域，*stage* 由您在部署 API 时指定。
URL 的主机名部分（即 `api-id.execute-api.region.amazonaws.com`）是指 API 端点。默认 API 端点名称是随机生成的，难以重新调用，对用户不友好。
使用自定义域名，您可以设置 API 的主机名，并选择基本路径（例如 `myservice`）以将备用 URL 映射到 API。例如，一个更为用户友好的 API 基本 URL 可以变成：
```
https://api.example.com/myservice
```
**注意**
有关私有 API 的自定义域名的更多信息，请参阅[API Gateway 中私有 API 的自定义域名](apigateway-private-custom-domains.md)。
## 注意事项
以下注意事项可能会影响您对自定义域名的使用：
+ 您可以禁用 API 的默认端点。客户端仍然可以连接到您的默认端点，但它们会收到 `403 Forbidden` 状态码。
+ 区域自定义域名可以与 REST API 和 HTTP API 相关联。您可以使用 [API Gateway 版本 2 API](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/api-reference.html) 为 REST API 创建和管理区域自定义域名。
+ 自定义域名跨所有 AWS 账户在一个区域内必须是唯一的。
+ 您可以在边缘优化端点和区域端点之间迁移自定义域名，但您无法将公共自定义域迁移到私有自定义域名。
+ 您必须创建或更新 DNS 提供程序的资源记录以映射到您的 API 端点。如果没有此类映射，针对自定义域名的 API 请求无法到达 API Gateway。
+ 您可以使用通配符证书，在不超过默认配额的情况下支持几乎无限数量的域名。有关更多信息，请参阅 [通配符自定义域名](#wildcard-custom-domain-names)。
+ 您可以为自定义域名选择安全策略。有关更多信息，请参阅 [选择针对 API Gateway 中自定义域的安全策略](apigateway-custom-domain-tls-version.md)。
+ 要配置具有多个级别的 API 映射，您必须使用区域自定义域名并使用 TLS 1.2 安全策略。
## 自定义域名的先决条件
以下是创建公共或私有自定义域名的先决条件。有关私有 API 的自定义域名的更多信息，请参阅[API Gateway 中私有 API 的自定义域名](apigateway-private-custom-domains.md)。
### 注册域名
您必须拥有已注册的 Internet 域名，以便为 API 设置自定义域名。您可以使用 [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) 或使用您选择的第三方域注册商注册互联网域名。自定义域名可以是注册的互联网域的子域或根域（也称为“机构根网域”）名称。
域名必须遵循 [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) 规范，每个标签最多可以有 63 个八位字节，总共可以有 255 个八位字节。
### 为您的自定义域名配置证书
为 API 设置自定义域名之前，您必须先在 ACM 中准备好 SSL/TLS 证书。如果 ACM 在您要创建自定义域名的 AWS 区域中不可用，您必须将证书导入到该区域的 API Gateway。
要导入 SSL/TLS 证书，您必须针对自定义域名提供 PEM 格式的 SSL/TLS 证书文本、其私有密钥和证书链。
存储在 ACM 中的每个证书均由其 ARN 标识。如果拥有 ACM 颁发的证书，那么您就无需担心公开任何敏感的证书详细信息，如私有密钥。要针对域名使用 AWS 托管的证书，您只需参考其 ARN 即可。
如果您的应用程序使用证书固定（有时称为 SSL 固定）来固定 ACM 证书，则在 AWS 续订证书后，应用程序可能无法连接到您的域。有关更多信息，请参阅《AWS Certificate Manager 用户指南》**中的[证书固定问题](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html)。
## 通配符自定义域名
使用通配符自定义域名，您可以在不超过[默认配额](limits.md)的情况下支持几乎无限数量的域名。例如，您可以为每位客户提供自己的域名 `customername.example.com`。
要创建通配符自定义域名，可以指定通配符 (`*`) 作为表示根域所有可能子域的自定义域的第一个子域。
例如，通配符自定义域名 `*.example.com` 生成 `a.example.com`、`b.example.com` 和 `c.example.com` 等子域。创建通配符自定义域名时，其所有子域名均按通配符域名的路由模式进行路由。要将子域路由到不同的 API，您可以执行以下任一操作：
+ 使用路由规则，通过 `Host` 标头将针对 `*.example.com` 的传入请求路由到不同的目标 REST API。有关更多信息，请参阅 [示例 4：通配符域名的路由规则](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-for-wildcard-domains)。
+ 为您想要路由到不同端点的任何子域名创建域名。在单个 AWS 账户中，您可以同时具有 `*.example.com` 和 `a.example.com`。
您可以使用 `$context.domainName` 和 `$context.domainPrefix` 上下文变量来确定客户端用于调用 API 的域名。要了解有关上下文变量的更多信息，请参阅 [API Gateway 的用于数据转换的变量](api-gateway-mapping-template-reference.md)。
要创建通配符自定义域名，您必须提供已使用 DNS 或电子邮件验证方法验证的由 ACM 颁发的证书。
**注意**
如果其他 AWS 账户已经创建了与通配符自定义域名冲突的自定义域名，则无法创建通配符自定义域名。例如，如果账户 A 已经创建了 `a.example.com`，则账户 B 无法创建通配符自定义域名 `*.example.com`。
如果账户 A 和账户 B 共享拥有者，您可以联系 [AWS Support 中心](https://console.aws.amazon.com/support/home#/)请求例外。
## 自定义域名的后续步骤
以下是自定义域名的后续步骤。
**后续步骤**
+ 要了解如何设置 SSL/TLS 证书，请参阅[在 AWS Certificate Manager 中准备好证书](how-to-specify-certificate-for-custom-domain-name.md)。
+ 要了解如何创建区域自定义域名，请参阅[在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)。
+ 要了解如何创建边缘优化的自定义域名，请参阅[为 API Gateway API 设置边缘优化的自定义域名](how-to-edge-optimized-custom-domain-name.md)。
+ 要了解如何在区域自定义域名和边缘优化的自定义域名之间迁移，请参阅[将自定义域名迁移至 API Gateway 中的其他 API 端点](apigateway-regional-api-custom-domain-migrate.md)。
+ 要了解如何将 API 阶段连接到自定义域名，请参阅[在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。
+ 要了解如何为自定义域名选择安全策略，请参阅[选择针对 API Gateway 中自定义域的安全策略](apigateway-custom-domain-tls-version.md)。
+ 要了解如何关闭自定义域名的默认端点，请参阅[禁用 REST API 的默认端点](rest-api-disable-default-endpoint.md)。
+ 要了解如何使用 Route 53 运行状况检查从 API Gateway API 控制 DNS 故障转移，请参阅[为 API Gateway API 配置针对 DNS 故障转移的自定义运行状况检查](dns-failover.md)。
如果这是您第一次创建自定义域名，我们建议您首先[在 AWS Certificate Manager 中准备好证书](how-to-specify-certificate-for-custom-domain-name.md)，以便指定您的证书，然后再[在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)，以便创建区域自定义域名。
# 在 AWS Certificate Manager 中准备好证书
为 API 设置自定义域名之前，您必须先在 AWS Certificate Manager 中准备好 SSL/TLS 证书 有关更多信息，请参阅[《AWS Certificate Manager 用户指南》](https://docs.aws.amazon.com/acm/latest/userguide/)。
## 注意事项
以下是 SSL/TLS 证书的注意事项。
+ 如果您创建边缘优化的自定义域名，API Gateway 将利用 CloudFront 来支持自定义域名的证书。因此，自定义域名 SSL/TLS 证书的要求和限制由 [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html) 决定。例如，公有密钥的最大大小为 2048，而私有密钥大小可以是 1024、2048 和 4096。公有密钥的大小取决于所用的证书颁发机构。要求证书颁发机构返回大小不同于默认长度的密钥。有关更多信息，请参阅[安全访问对象](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https.html)和[创建签名 URL 和签名 Cookie](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html)。
+ 如果创建区域自定义域名，则公有密钥的最大大小为 2048。
+ 要将 ACM 证书与区域自定义域名结合使用，您必须在与 API 相同的区域中请求或导入证书。证书必须涵盖自定义域名。
+ 要将 ACM 证书与边缘优化的自定义域名结合使用，您必须在美国东部（弗吉尼亚州北部） - `us-east-1` 区域中请求或导入证书。
+ 您必须有一个已注册的域名，例如 `example.com`。您可以使用 [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) 或获得认可的第三方域注册商。要获取此类注册商的列表，请参阅 ICANN 网站上[获得认可的注册商目录](https://www.icann.org/en/accredited-registrars)。
## 在 ACM 中创建或导入 SSL/TLS 证书
以下过程说明了如何为域名创建或导入 SSL/TLS 证书。
------
#### [ To request a certificate provided by ACM for a domain name ]
1. 登录到 [AWS Certificate Manager 控制台](https://console.aws.amazon.com/acm)。
1. 选择**请求证书**。
1. 对于**证书类型**，选择**请求公有证书**。
1. 选择**下一步**。
1. 对于**完全限定域名**，为您的 API 输入一个自定义域名，例如 `api.example.com`。
1. （可选）选择**向此证书添加一个名称**。
1. 对于**验证方法**，选择一种验证域名所有权的方法。
1. 对于**密钥算法**，选择一种加密算法。
1. 选择**请求**。
1. 如果请求有效，Internet 域中注册的拥有者必须同意请求，然后 ACM 才能颁发证书。如果您使用 Route 53 管理您的公有 DNS 记录，则可以直接通过 ACM 控制台更新您的记录。
------
#### [ To import into ACM a certificate for a domain name ]
1. 从证书颁发机构为自定义域名获取 PEM 编码的 SSL/TLS 证书。要获取此类 CA 的部分列表，请参阅 [Mozilla 内置 CA 列表](https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReport)
1. 使用 OpenSSL 网站中的 [OpenSSL](https://www.openssl.org) 工具包生成证书的私有密钥并将输出结果保存到文件中：
```
openssl genrsa -out private-key-file 2048
```
1. 使用 OpenSSL 通过之前生成的私有密钥生成证书签名请求 (CSR)：
```
openssl req -new -sha256 -key private-key-file -out CSR-file
```
1. 将 CSR 提交给证书颁发机构并保存生成的证书。
1. 从证书颁发机构下载证书链。
**注意**
如果您通过其他方式获取了私有密钥并且密钥已加密，则您可以使用以下命令解密密钥，然后再将其提交到 API Gateway 以便设置自定义域名。
```
openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem
```
1. 将证书上传到 AWS Certificate Manager：
1. 登录到 [AWS Certificate Manager 控制台](https://console.aws.amazon.com/acm)。
1. 选择**导入证书**。
1. 对于**证书正文**，输入从证书颁发机构提供的 PEM 格式的服务器证书的正文。下面显示了此类证书的简短示例。
```
-----BEGIN CERTIFICATE-----
EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB
...
az8Cg1aicxLBQ7EaWIhhgEXAMPLE
-----END CERTIFICATE-----
```
1. 对于**证书私有密钥**，输入 PEM 格式的证书的私有密钥。下面显示了此类密钥的简短示例。
```
-----BEGIN RSA PRIVATE KEY-----
EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO
...
1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE
-----END RSA PRIVATE KEY-----
```
1. 对于**证书链**，输入 PEM 格式的中间证书和根证书（可选），一个接一个，不带任何空白行。如果包含了根证书，您的证书链必须以中间证书开始，以根证书结尾。使用证书颁发机构提供的中间证书。不要包含未在信任路径链中的任何中间证书。下面显示了一个简短示例。
```
-----BEGIN CERTIFICATE-----
EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB
...
8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE
-----END CERTIFICATE-----
```
以下是另一个示例。
```
-----BEGIN CERTIFICATE-----
Intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Optional: Root certificate
-----END CERTIFICATE-----
```
1. 选择**下一步**，然后再次选择**下一步**。
------
成功创建或导入证书后，请记下证书的 ARN。您在设置自定义域名时会需要它。
# 在 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*)。
------
# 为 API Gateway API 设置边缘优化的自定义域名
为边缘优化的 API 创建自定义域名时，API Gateway 会设置 CloudFront 分配和 DNS 记录，以将 API 域名映射到 CloudFront 分配域名。然后，对 API 的请求将通过映射的 CloudFront 分配路由到 API Gateway。此映射适用于针对要通过映射的 CloudFront 分配路由到 API Gateway 的自定义域名绑定的 API 请求。
## 注意事项
以下是边缘优化的自定义域名的注意事项：
+ 要设置边缘优化的自定义域名或更新其证书，您必须有权更新 CloudFront 分配。
更新 CloudFront 分配需要以下权限：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCloudFrontUpdateDistribution",
"Effect": "Allow",
"Action": [
"cloudfront:updateDistribution"
],
"Resource": [
"*"
]
}
]
}
```
------
+ 您必须为您在美国东部（弗吉尼亚州北部）- `us-east-1` 区域的边缘优化自定义域名请求或导入证书。
+ API Gateway 创建的 CloudFront 分配由与 API Gateway 关联的区域特定账户拥有。当跟踪操作以在 CloudTrail 中创建和更新此类 CloudFront 分配时，您必须使用此 API Gateway 账户 ID。有关更多信息，请参阅 [在 CloudTrail 中记录自定义域名的创建操作](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail)。
+ API Gateway 在 CloudFront 分配上通过利用服务器名称指示 (SNI) 来支持边缘优化的自定义域名。有关在 CloudFront 分配上使用自定义域名的更多信息（包括所需证书格式和证书密钥最大长度），请参阅 *Amazon CloudFront 开发人员指南* 中的[使用备用域名和 HTTPS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html)。
+ 边缘优化的自定义域名需要大约 40 分钟时间准备就绪。
+ 创建边缘优化的自定义域名后，您必须创建 DNS 记录，以将自定义域名映射到 CloudFront 分配名称。
## 创建边缘优化的自定义域名
以下过程说明了如何为 API 创建边缘优化的自定义域名。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择**添加域列表**。
1. 对于**域名**，输入一个域名。
1. 对于**路由模式**，选择 **API\$1MAPPING\$1ONLY**。
1. 对于**端点类型**，选择**边缘优化**。
1. 选择最低 TLS 版本。
1. 选择 ACM 证书。
1. 选择**添加域列表**。
------
#### [ REST API ]
1. 调用 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)，并指定自定义域名和 AWS Certificate Manager 中所存储证书的 ARN。
成功的 API 调用将返回 `201 Created` 响应，其中包含证书 ARN 以及负载中关联的 CloudFront 分配名称。
1. 请记下输出中显示的 CloudFront 分配域名。您在下一步中在 DNS 中设置自定义域的 A 记录别名目标时需要此域名。
有关此 REST API 调用的代码示例，请参阅 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)。
------
边缘优化的自定义域名需要大约 40 分钟时间准备就绪，但控制台会立即以 `distribution-id.cloudfront.net` 的形式显示关联的 CloudFront 分配域名以及证书 ARN。同时，您可以创建基本路径映射或路由规则，然后配置 DNS 记录别名，以便将自定义域名映射到关联的 CloudFront 分配域名。
## 配置 API 的基本路径映射，将自定义域名作为主机名
因为您将路由模式设置为 `API_MAPPING_ONLY`，所以您可以使用基本路径映射来将单个自定义域名用作多个 API 的主机名。这样，您就可以通过自定义域名和关联基本路径的组合访问 API。
例如，如果您在 API Gateway 中创建了一个名为 `PetStore` 的 API 和另一个名为 `Dogs` 的 API，然后设置了一个自定义域名 `api.example.com`，则可以将 `PetStore` API 的 URL 设置为 `https://api.example.com`。
这会将 `PetStore` API 与空字符串的基本路径相关联。如果您将 `PetStore` API 的 URL 设置为 `https://api.example.com/PetStore`，系统会将 `PetStore` API 与 `PetStore` 基本路径相关联。您可以为 `MyDogList` API 分配 `Dogs` 基本路径。然后，`https://api.example.com/MyDogList` 的 URL 就成了 `Dogs` API 的根 URL。
要在多个级别上配置 API 映射，您只能使用区域自定义域名。不支持边缘优化的自定义域名。有关更多信息，请参阅 [使用 API 映射将 API 阶段连接到 REST API 的自定义域名](rest-api-mappings.md)。
以下过程设置 API 映射，将您的自定义域名的路径映射到 API 阶段。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从 API Gateway 控制台的主导航窗格中选择**自定义域名**。
1. 选择自定义域名。
1. 选择**配置 API 映射**。
1. 选择**添加新映射**。
1. 指定映射的 **API**、**阶段**和**路径**（可选）。
1. 选择**保存**。
------
#### [ REST API ]
在特定自定义域名上调用 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)，并指定 `basePath`、`restApiId` 和请求负载中的一个部署 `stage` 属性。
成功的 API 调用将返回 `201 Created` 响应。
有关 REST API 调用的代码示例，请参阅 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)。
------
为了更灵活地将流量路由到 API，可以将路由模式更改为 `ROUTING_RULE_ONLY` 或 `ROUTING_RULE_THEN_API_MAPPING`，然后创建路由规则。有关更多信息，请参阅 [在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。
## 为边缘优化的自定义域名创建 DNS 记录
在开始创建边缘优化的自定义域名后，请设置 DNS 记录别名。
我们建议您使用 Route 53 为自定义域名创建 A 记录别名，同时指定 CloudFront 分配域名作为别名目标。这意味着，Route 53 可以路由自定义域名，即使是顶级域名也是如此。有关更多信息，请参阅 *Amazon Route 53 开发人员指南* 中的[在别名资源记录集和非别名资源记录集之间进行选择](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html)。
有关 Amazon Route 53 的说明，请参阅 *Amazon Route 53 开发人员指南*中的[使用域名将流量路由到 Amazon API Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。
## 在 CloudTrail 中记录自定义域名的创建操作
启用 CloudTrail 以记录您的账户发出的 API Gateway 调用时，API Gateway 会在为 API 创建或更新自定义域名时记录关联的 CloudFront 分配更新。这些日志在 `us-east-1` 中提供。由于这些 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 |
## 轮换 ACM 中导入的证书
ACM 会自动处理其所颁发证书的续订事宜。您不需要为自定义域名轮换 ACM 颁发的任何证书。CloudFront 会代表您处理这一事宜。
但是，如果您将证书导入到 ACM 并将其用于自定义域名，则您必须在证书到期前进行轮换。这包括导入域名的新第三方证书和将现有证书轮换为新证书。新导入的证书到期后，您需要重复上述过程。或者，您也可以请求 ACM 为域名颁发新证书并将现有证书轮换为 ACM 颁发的新证书。之后，您就可以让 ACM 和 CloudFront 自动为您处理证书轮换。要创建或导入新的 ACM 证书，请按照[在 ACM 中创建或导入 SSL/TLS 证书](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup)中的步骤操作。
以下过程说明了如何为域名轮换证书。
**注意**
轮换导入到 ACM 的证书大约需要 40 分钟。
------
#### [ AWS 管理控制台 ]
1. 在 ACM 中请求或导入证书。
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从 API Gateway 控制台的主导航窗格中选择**自定义域名**。
1. 选择边缘优化的自定义域名。
1. 对于**端点配置**，请选择**编辑**。
1. 从 **ACM 证书**下拉列表中选择证书。
1. 选择**保存更改**，开始轮换自定义域名的证书。
------
#### [ REST API ]
调用 [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html) 操作，并为特定域名指定新 ACM 证书的 ARN。
------
#### [ AWS CLI ]
以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 更新边缘优化域名的 ACM 证书。
```
aws apigateway update-domain-name \
--domain-name edge.example.com \
--patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 更新区域域名的 ACM 证书。
```
aws apigateway update-domain-name \
--domain-name regional.example.com \
--patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
------
## 使用基本路径映射时，通过自定义域名调用 API
如果使用的 URL 正确，则调用具有自定义域名的 API 与调用具有默认域名的 API 是一样的。
以下示例针对两个 API（`udxjef` 和 `qf3duz`），将它们在指定区域 (`us-east-1`) 的一组默认 URL 与其给定自定义域名 (`api.example.com`) 下的相应自定义 URL 进行了对比。
| API ID | 阶段 | 默认 URL | 基本路径 | 自定义 URL |
| --- | --- | --- | --- | --- |
| udxjef | prod | https://udxjef.execute-api.us-east-1.amazonaws.com/prod | /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，可以创建路由规则。有关更多信息，请参阅 [在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。
API Gateway 通过使用[服务器名称指示 (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) 来支持 API 的自定义域名。您可以使用浏览器或支持 SNI 的客户端库调用具有自定义域名的 API。
API Gateway 在 CloudFront 分配中强制实施 SNI。有关 CloudFront 如何使用自定义域名的信息，请参阅 [Amazon CloudFront 自定义 SSL](https://aws.amazon.com/cloudfront/custom-ssl-domains/)。
# 将自定义域名迁移至 API Gateway 中的其他 API 端点
您可以在边缘优化和区域端点之间迁移自定义域名。您无法将公共自定义域名迁移到私有自定义域名。首先，您向自定义域名的现有 `endpointConfiguration.types` 列表添加新端点配置类型。接下来，您设置 DNS 记录，将自定义域名指向新预配置的端点。最后，移除过时的自定义域名端点。
## 注意事项
下面是在区域 API 端点和边缘优化的 API 端点之间迁移自定义域名的注意事项：
+ 边缘优化的自定义域名需要美国东部（弗吉尼亚州北部）- `us-east-1` 区域的 ACM 提供的证书。此证书分发到所有地理位置。
+ 区域自定义域名需要托管 API 的同一区域的 ACM 提供的证书。您可以从 API 本地的区域请求新 ACM 证书，将不在 `us-east-1` 区域中的边缘优化自定义域名迁移到区域自定义域名。
+ 边缘优化自定义域名和区域自定义域名之间的迁移最多可能需要 60 秒才能完成。迁移时间还取决于您何时更新 DNS 记录。
+ 只有将端点访问模式设置为 `BASIC` 时，才能添加其他端点配置。拥有两项端点配置后，您将无法再更改端点访问模式。有关更多信息，请参阅 [端点访问模式](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)。
+ 如果您的自定义域名使用以 `SecurityPolicy_` 开头的安全策略，则在添加新的端点配置类型时，两种端点类型的端点访问模式将是相同的，并且您必须为新的端点配置类型选择以 `SecurityPolicy_` 开头的安全策略。
## 迁移自定义域名
**注意**
要完成迁移，请务必从自定义域名中移除过时的端点。
以下过程说明了如何将边缘优化的自定义域名迁移到区域自定义域名。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择边缘优化的自定义域名。
1. 对于**端点配置**，请选择**编辑**。
1. 选择**添加区域端点**。
1. 对于 **ACM 证书**，选择一个证书。
区域证书必须与区域 API 位于相同区域。
1. 选择**保存更改**。
1. 设置 DNS 记录以将区域自定义域名指向此区域主机名。有关更多信息，请参阅[配置 Route 53 以将流量路由到 API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。
1. 确认 DNS 配置使用了正确的端点后，删除边缘优化的端点配置。选择您的自定义域名，然后对于**边缘优化端点配置**，请选择**删除**。
1. 确认您的选择并删除端点。
------
#### [ AWS CLI ]
使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令将边缘优化的自定义域名迁移到区域自定义域名：
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
区域证书必须与区域 API 位于相同区域。
输出将与以下内容类似：
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
对于迁移后的区域自定义域名，生成的 `regionalDomainName` 属性返回区域 API 主机名。您必须设置 DNS 记录以将区域自定义域名指向此区域主机名。这使绑定到自定义域名的流量可以路由到区域主机。
设置 DNS 记录后，您可以删除边缘优化的自定义域名。使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令删除边缘优化的自定义域名：
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
以下步骤演示了如何将使用增强型安全策略的边缘优化型自定义域名改为同样使用增强型安全策略的区域自定义域名。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择边缘优化的自定义域名。
1. 对于**端点配置**，请选择**编辑**。
1. 选择**添加区域端点**。
1. 对于 **ACM 证书**，选择一个证书。
区域证书必须与区域 API 位于相同区域。
1. 对于**安全策略**，请选择以 `SecurityPolicy_` 开头的安全策略。
1. 对于**端点访问模式**，请选择**基本**。
1. 选择**保存更改**。
1. 设置 DNS 记录以将区域自定义域名指向此区域主机名。有关更多信息，请参阅[配置 Route 53 以将流量路由到 API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。
1. 确认 DNS 配置使用了正确的端点后，删除边缘优化的端点配置。选择您的自定义域名，然后对于**边缘优化端点配置**，请选择**删除**。
1. 确认您的选择并删除端点。
------
#### [ AWS CLI ]
使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令将边缘优化的自定义域名迁移到区域自定义域名：
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"replace", "path": "/securityPolicy", "value":"SecurityPolicy_TLS13_1_3_2025_09"},
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
区域证书必须与区域 API 位于相同区域。
输出将与以下内容类似：
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "BASIC",
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
对于迁移后的区域自定义域名，生成的 `regionalDomainName` 属性返回区域 API 主机名。您必须设置 DNS 记录以将区域自定义域名指向此区域主机名。这使绑定到自定义域名的流量可以路由到区域主机。
设置 DNS 记录后，您可以删除边缘优化的自定义域名。使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令删除边缘优化的自定义域名：
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
以下过程说明了如何将区域自定义域名迁移到边缘优化的自定义域名。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主导航窗格中，选择**自定义域名**。
1. 选择区域自定义域名
1. 对于**端点配置**，请选择**编辑**。
1. 选择**添加边缘优化的端点**。
1. 对于 **ACM 证书**，选择一个证书。
边缘优化的域证书必须在 `us-east-1` 区域中创建。
1. 选择**保存**。
1. 设置 DNS 记录以将边缘优化自定义域名指向此边缘优化主机名。有关更多信息，请参阅[配置 Route 53 以将流量路由到 API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。
1. 确认 DNS 配置使用了正确的端点后，删除区域端点配置。选择您的自定义域名，然后对于**区域端点配置**，请选择**删除**
1. 确认您的选择并删除端点。
------
#### [ AWS CLI ]
使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令将区域自定义域名迁移到边缘优化的自定义域名：
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
{ "op":"add", "path": "/certificateName", "value": "edge-cert" },
{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
]'
```
边缘优化的域证书必须在 `us-east-1` 区域中创建。
输出将与以下内容类似：
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
"regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}
```
对于指定的自定义域名，API Gateway 将返回边缘优化的 API 主机名作为 `distributionDomainName` 属性值。您必须设置 DNS 记录以将边缘优化自定义域名指向此分配域名。这使绑定到边缘优化的自定义域名的流量可以路由到边缘优化的 API 主机名。
设置 DNS 记录之后，您可以删除自定义域名的 `REGION` 端点类型：使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令删除区域端点类型：
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
{"op":"remove", "path":"regionalCertificateArn"}
]'
```
输出内容如下所示：
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": "EDGE"
}
}
```
------
# 在 API Gateway 中通过自定义域名将流量发送到 API
在为自定义域名配置路由模式时，可以设置如何将传入流量定向到 API。可以使用路由规则、API 映射或路由规则和 API 映射将流量发送到 API。下一节说明何时使用路由规则、何时使用 API 映射以及如何为自定义域名设置路由模式。
## 何时使用路由规则
使用路由规则时，可以将与特定条件相匹配的传入请求定向到特定的 REST API 阶段。例如，如果规则包含标头 `version:v1` 和基本路径 `/users`，则此规则可以将请求路由到 `users` REST API 的 `production` 阶段。使用路由规则来创建高级动态路由拓扑，以支持诸如 A/B 测试或新版本 API 的使用不断增加等使用案例。
我们建议在将流量定向到 REST API 时，对自定义域名使用路由规则。可以使用路由规则来重新创建任何 API 映射。有关更多信息，请参阅 [使用路由规则重新创建 API 映射](rest-api-routing-rules-recreate-api-mapping.md)。
对于 REST API，还可以结合使用路由规则和 API 映射。当您结合使用路由规则和 API 映射时，API Gateway 始终在评估任何 API 映射之前评估路由规则。结合使用路由规则和 API 映射来迁移您当前的自定义域名或探索路由规则。
### 路由规则注意事项
以下注意事项可能会影响您对路由规则的使用：
+ 不支持将 WebSocket 或 HTTP API 作为路由规则的目标 API。
+ 如果自定义域名具有到 REST 和 HTTP API 的 API 映射，则不支持路由规则。
+ 可以为私有自定义域创建指向私有 REST API 的路由规则。可以为公有自定义域创建指向区域或边缘优化 API 的路由规则。
+ 无法为公有自定义域创建指向私有 API 的路由规则。无法为私有自定义域名创建指向公有 API 的路由规则。
## 在路由规则与 API 映射之间选择
我们建议您在可能的情况下使用路由规则。仅使用 API 映射将流量发送到 HTTP 或 WebSocket API。
# 为自定义域名设置路由模式
您可以选择 API Gateway 使用哪种路由模式将流量路由到 API。有关更多信息，请参阅 [在 API Gateway 中通过自定义域名将流量发送到 API](rest-api-routing-mode.md)。本节讨论自定义域名的路由模式。您必须为自定义域名设置路由模式，才能将流量路由到 API。支持以下路由模式：
+ **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**：使用此模式通过路由规则和 API 映射将流量发送到 API。在这种模式下，所有路由规则的优先级均高于任何 API 映射。有关此模式的示例，请参阅[示例 2：路由规则和 API 映射](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings)。
+ **ROUTING\$1RULE\$1ONLY**：使用此模式以仅支持路由规则向 API 发送流量。当自定义域名使用此模式时，您无法创建 API 映射，但可以使用 [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) 命令来查看它们。API 调用方无法使用 API 映射来访问此域名。
+ **API\$1MAPPING\$1ONLY**：使用此模式以仅支持 API 映射向 API 发送流量。当自定义域名使用此模式时，您无法创建路由规则，但可以使用 `list-routing-rules` 命令来查看它们。API 调用方无法使用路由规则来访问此域名。
这是您所有现有域名以及您创建的任何新域名的默认路由模式。
当您使用 `apigateway` 创建自定义域名时，`API_MAPPING_ONLY` 称为 `BASE_PATH_MAPPING_ONLY`，而 `ROUTING_RULE_THEN_API_MAPPING` 称为 `ROUTING_RULE_THEN_BASE_PATH_MAPPING`。此行为仅适用于 AWS CLI、CloudFormation 或任何 SDK，但不存在于 AWS 管理控制台中。
以下过程说明如何更改现有自定义域名的路由模式。当您更改自定义域名的路由模式时，API 调用方无法使用任何不支持的路由模式访问域名。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择自定义域名。
1. 对于**域详细信息**，选择**编辑**。
1. 对于**路由模式**，请选择 **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**。
1. 选择**保存**。
如果您将路由模式更改为 `ROUTING_RULE_ONLY` 或 `API_MAPPING_ONLY`，则将从控制台的域名详细信息页面中移除您创建的任何 API 映射或路由规则。如果您更改路由模式以支持路由规则或 API 映射，则这些资源将返回。
------
#### [ AWS CLI - apigatewayv2 ]
以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 命令将域名更新为使用路由模式 `ROUTING_RULE_THEN_API_MAPPING`：
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
输出将与以下内容类似：
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令将私有自定义域名更新为使用路由模式 `ROUTING_RULE_THEN_BASE_PATH_MAPPING`：
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
输出将与以下内容类似：
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# 将 API 阶段连接到 REST API 的自定义域名的路由规则
路由规则是一组条件，匹配时会调用操作。例如，规则可以将任何传入的请求路由到自定义域名，该域名包含标头 `Hello:World` 并包含指向 REST API 的 `production` 阶段的基本路径 `users`。
规则按优先级顺序进行评估，如果您将路由模式设置为 `ROUTING_RULE_THEN_API_MAPPING`，则 API Gateway 将始终在评估任何 API 映射之前评估所有路由规则。以下列表描述了路由规则如何使用条件、操作和优先级。
**条件**
当规则的条件满足时，将执行其操作。API Gateway 最多支持两个标头条件和一个路径条件。API Gateway 会一起评估标头条件和基本路径条件。
您可以创建不带任何条件的规则。当 API Gateway 评估此规则时，将始终执行该操作。您可以创建不带任何条件的规则作为“捕获全部”规则。
有关标头条件的更多信息，请参阅[匹配标头条件](#rest-api-routing-rules-condition-headers)。有关路径条件的更多信息，请参阅[匹配基本路径条件](#rest-api-routing-rules-condition-path)。
**操作**
操作是将条件与路由规则匹配的结果。当前，唯一受支持的操作是调用 REST API 的阶段。
每条规则可以有一个操作。
**优先级**
优先级决定了评估规则的顺序（从最低值到最高值）。规则不能具有相同的优先级。
您可以将优先级设置为 1-1000000。如果规则的优先级为 1，则 API Gateway 首先对其进行评估。我们建议在创建规则时，在优先级间添加间隔。这有助于您切换规则的优先级并添加新规则。有关更多信息，请参阅 [更改路由规则的优先级](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority)。
有关 API Gateway 如何评估路由规则的示例，请参阅[有关 API Gateway 如何评估路由规则的示例](rest-api-routing-rules-examples.md)。
## API Gateway 路由规则条件类型
下一节介绍路由规则条件类型。仅当所有条件均为 true 时，API Gateway 才会匹配规则。
### 匹配标头条件
创建标头条件时，可以匹配标头名称和标头 glob 值，例如 `Hello:World`。API Gateway 使用文字匹配来验证匹配标头条件。您的条件最多可以使用两个标头，并在标头之间使用 `AND`。例如，如果传入的请求包含 `Hello:World` 和 `x-version:beta`，则条件可以匹配。
标头名称匹配不区分大小写，但标头 glob 值区分大小写。`Hello:World` 将匹配 `hello:World`，但不匹配 `Hello:world`。
有关受限标头值的列表，请参阅[限制](#rest-api-routing-rules-restrictions)。
#### 将通配符与标头条件结合使用
只能在标头 glob 值中使用通配符，并且通配符必须是 `*prefix-match`、`suffix-match*` 或 `*contains*`。下表显示了如何使用通配符来匹配标头条件的示例。
| 标头条件 | 与路由规则匹配的请求 | 与路由规则不匹配的请求 |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` 和 `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` 和 `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | 无 |
如果您为多个标头值创建条件（例如 `Accept:application/json,text/xml`），我们建议您将 `*contains*` 用于标头条件，并避免使用逗号 (`,`) 字符创建条件。
由于 API Gateway 按字面匹配标头条件，因此可能会以不同的方式路由语义匹配。下表显示了路由规则结果的差异。
| 标头条件 | 与路由规则匹配的请求 | 与路由规则不匹配的请求 |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html) | 无 |
### 匹配基本路径条件
创建基本路径条件时，如果传入的请求包含您指定的路径，则匹配该规则。匹配区分大小写，因此路径 `New/Users` 将与 `new/users` 不匹配。
您只能为一条基本路径创建基本路径条件。
有关受限基本路径条件的列表，请参阅[限制](#rest-api-routing-rules-restrictions)。
#### 使用基本路径条件删除基本路径
创建基本路径条件时，可以选择剥离基本路径。当您删除基本路径时，API Gateway 会在调用目标 API 时移除传入的匹配基本路径。这与您使用 API 映射时的行为相同。当您不删除基本路径时，API Gateway 会将整个基本路径转发到目标 API。我们建议您仅在重新创建 API 映射时才删除基本路径。
下表显示了 API Gateway 如何评估删除基本路径条件的示例。
| 条件 | 删除基本路径 | 传入请求 | 结果 |
| --- | --- | --- | --- |
| 如果基本路径包含 `PetStoreShopper/dogs` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway 调用 `/` 资源的 `GET` 方法。 |
| 如果基本路径包含 `PetStoreShopper/dogs`。 | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway 调用 `PetStoreShopper/dogs` 资源的 `GET` 方法。 |
| 如果基本路径包含 `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway 调用 `dogs` 资源的 `GET` 方法。 |
| 如果基本路径包含 `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway 调用 `PetStoreShopper/dogs` 资源的 `GET` 方法。 |
| 如果基本路径包含 `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway 使用查询字符串参数 `birds=available` 调用 `/` 资源的 `GET` 方法。 |
| 如果基本路径包含 `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway 使用查询字符串参数 `birds=available` 调用 `/PetStoreShopper` 资源的 `GET` 方法。 |
## 限制
+ 目标 API 和自定义域名必须位于同一个 AWS 账户中。
+ 每条规则可以有一个目标 API。
+ 您只能为私有自定义域名创建指向私有 API 的路由规则，以及为公有自定义域名创建指向公有 API 的路由规则。您不能混合公有资源和私有资源。
+ 如果自定义域名具有到 REST 和 HTTP API 的 API 映射，则不支持路由规则。
+ 最大优先级数字为 1000000。
+ 标头限制：
+ 每个 `anyOf` 条件只能包含一个标头值。
+ [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230) 规定了标头名称和标头 glob 值支持的仅有字符，即 `a-z`、`A-Z`、`0-9` 和以下特殊字符：`*?-!#$%&'.^_`|~`。
+ 可以在标头 glob 值中使用通配符，但通配符必须为 `*prefix-match`、`suffix-match*` 或 `*contains*`。不能在标头 glob 值的中间使用 `*`。
+ 不支持通配符标头名称。
+ 标头名称必须少于 40 个字符。
+ 标头 glob 值必须少于 128 个字符。
+ 中缀匹配的标头 glob 值必须少于 40 个字符。
+ 不支持将以下标头作为条件：
+ `access-control-*`
+ `apigw-*`
+ `Authorization`
+ `Connection`
+ `Content-Encoding`
+ `Content-Length`
+ `Content-Location`
+ `Forwarded`
+ `Keep-Alive`
+ `Origin`
+ `Proxy-Authenticate`
+ `Proxy-Authorization`
+ `TE`
+ `Trailers`
+ `Transfer-Encoding`
+ `Upgrade`
+ `x-amz-*`
+ `x-amzn-*`
+ `x-apigw-api-id`
+ `X-Forwarded-For`
+ `X-Forwarded-Host`
+ `X-Forwarded-Proto`
+ `x-restAPI`
+ `Via`
+ 基本路径限制：
+ 基本名称长度必须少于 128 个字符。
+ 基本路径必须仅包含字母、数字和以下字符：`$-_.+!*'()/`。
正则表达式不支持这些字符。
+ 基本路径不能以反斜杠 (`\`) 字符开头或结尾。
# 有关 API Gateway 如何评估路由规则的示例
下一节显示了有关 API Gateway 如何评估路由规则和 API 映射的四个示例。
## 示例 1：仅路由规则
在此示例中，自定义域名 `https://petstore.example.com` 的路由模式设置为 `ROUTING_RULE_ONLY`，并具有以下路由规则和优先级。
| 规则 ID | 优先级 | 条件 | 操作 |
| --- | --- | --- | --- |
| `abc123` | 10 | 如果请求包含标头：`Hello:World` | 目标 API 1 |
| `zzz000` | 50 | 如果请求包含标头：`Accept:image/webp` 和 `Pet:Dog-*` 且基本路径包含 `PetStoreShopper` | 目标 API 2 |
| `efg456` | 100 | 无 | 目标 API 3 |
下表显示了 API Gateway 如何将之前的路由规则应用于示例请求。
| 请求 | 选定的 API | 说明 |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | 目标 API 1 | 请求与路由规则 `abc123` 匹配。 |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | 目标 API 1 | API Gateway 按优先级顺序评估所有路由规则。路由规则 `abc123` 具有第一优先级且条件匹配，因此 API Gateway 调用目标 API 1。 尽管请求的条件也与路由规则 `zzz000` 匹配，但 API Gateway 在进行匹配后不会评估任何其它路由规则。 |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | 目标 API 2 | 请求与路由规则 `zzz000` 匹配。之所以匹配，是因为 `Pet:Dog-Bella` 是 `Pet:Dog-*` 的字符串匹配 |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | 目标 API 3 | 请求与路由规则 `abc123` 不匹配。请求与路由规则 `zzz000` 不匹配，因为所有必需的标头都不存在。下一个优先级规则匹配所有传入的请求，因此 API Gateway 调用目标 API 3。 |
## 示例 2：路由规则和 API 映射
在此示例中，自定义域名 `https://petstore.diagram.example.com` 的路由模式设置为 `ROUTING_RULE_THEN_API_MAPPING`，并具有以下路由规则和 API 映射。
| 规则 ID | 优先级 | 条件 | 操作 |
| --- | --- | --- | --- |
| `abc123` | 1 | 如果请求包含基本路径 `pets` | 调用 `PetStore` API 的 `Prod` 阶段。 |
| `000zzz` | 5 | 如果请求包含标头：`Cookie`:`*ux=beta*` 且基本路径包含 `/refunds` | 调用 `Refunds` API 的 `Beta` 阶段。 |
下表显示 `https://petstore.backup.example.com` 的 API 映射。
| API 映射 | 选定的 API |
| --- | --- |
| `/refunds` | 调用 `Refunds` API 的 `Prod` 阶段。 |
| `(none)` | 调用 `Search` API 的 `Prod` 阶段。 |
下图显示了 API Gateway 如何将之前的路由规则和 API 映射应用于示例请求。示例请求汇总在此图之后的表格中。
![\[API Gateway 如何应用之前的路由规则和 API 映射的示意图。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/rr-diagram.png)
下表说明了 API Gateway 如何将之前的路由规则和 API 映射应用于示例请求。
| 请求 | 选定的 API | 说明 |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | `PetStore` API 的 `Prod` 阶段。 | 请求与路由规则 `abc123` 匹配。 |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | `Refunds` API 的 `Beta` 阶段。 | 请求与路由规则 `000zzz` 匹配。`Cookie` 标头包含此条件的正确 `*contains*` 匹配和基本路径匹配。 |
| `https://petstore.diagram.example.com/refunds` | `Refunds` API 的 `Prod` 阶段。 | 该请求没有与路由规则 `zzz000` 匹配所需的标头。如果 API Gateway 无法成功地匹配路由规则，则它会回退到 API 映射。API Gateway 可以将基本路径映射到 `Refunds` API 的 `Prod` 阶段。 |
| `https://petstore.diagram.example.com/` | `Search` API 的 `Prod` 阶段。 | 该请求将 API 映射与空路径 `(none)` 匹配。 |
## 示例 3：具有多个级别的路由规则和 API 映射
在此示例中，自定义域名 `https://petstore.backup.example.com` 的路由模式设置为 `ROUTING_RULE_THEN_API_MAPPING`，并具有以下路由规则和 API 映射。
下表显示了 `https://petstore.backup.example.com` 的路由规则。
| 规则 ID | 优先级 | 条件 | 操作 |
| --- | --- | --- | --- |
| `abc123` | 10 | 如果请求包含标头：`Hello:World` | 目标 API 1 |
| `000zzz` | 50 | 如果请求包含标头：`Accept`:`image/webp` 和 `Pet:Dog-*` 且基本路径包含 `PetStoreShopper` | 目标 API 2 |
下表显示 `https://petstore.backup.example.com` 的 API 映射。
| API 映射 | 选定的 API |
| --- | --- |
| `PetStoreShopper` | 目标 API 3 |
| `PetStoreShopper/cats` | 目标 API 4 |
下表说明了 API Gateway 如何将之前的路由规则和 API 映射应用于示例请求。
| 请求 | 选定的 API | 说明 |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | 目标 API 3 | 该请求没有与路由规则 `zzz000` 匹配所需的标头。如果 API Gateway 无法成功地匹配路由规则，则它会回退到 API 映射。API Gateway 可以将基本路径映射到目标 API 3。 |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | 目标 API 1 | 请求与路由规则 `abc123` 匹配。如果路由模式设置为 `ROUTING_RULE_THEN_API_MAPPING`，则路由规则的优先级始终高于 API 映射。 |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | 无 | 请求与任何路由规则或 API 映射都不匹配。由于没有默认路由规则，因此 API Gateway 会拒绝调用，并向调用方发送 `403 Forbidden` 状态代码。 |
## 示例 4：通配符域名的路由规则
在此示例中，自定义域名 `https://*.example.com` 是通配符域名。通配符支持路由回同一个域的所有子域名。以下示例路由规则更改了这一行为，以支持子域名使用 `Host` 标头路由到不同的目标 API。
下表显示了 `https://*.example.com` 的路由规则。
| 规则 ID | 优先级 | 条件 | 操作 |
| --- | --- | --- | --- |
| `abc123` | 10 | 如果请求包含标头：`Host:a.example.com` | 目标 API 1 |
| `000zzz` | 50 | 如果请求包含标头：`Host:b.example.com` | 目标 API 2 |
| `efg456` | 500 | 无 | 目标 API 3 |
下表显示了 API Gateway 如何将之前的路由规则应用于示例请求。
| 请求 | 选定的 API | 说明 |
| --- | --- | --- |
| `https://a.example.com` | 目标 API 1 | `Host` 标头为 `a.example.com`。此请求与路由规则 `abc123` 匹配。 |
| `https://b.example.com` | 目标 API 2 | `Host` 标头为 `b.example.com`。此请求与路由规则 `000zzz` 匹配。 |
| `https://testing.example.com` | 目标 API 3 | 这与“捕获全部”路由规则 `efg456` 匹配。 |
# 如何使用路由规则
可以使用 AWS 管理控制台、AWS CLI 或任何 AWS SDK 创建路由规则。创建规则后，可以更改其优先级。
## 创建路由规则
以下过程说明如何在路由模式设置为 `ROUTING_RULE_THEN_API_MAPPING` 或 `ROUTING_RULE_ONLY` 的情况下，为自定义域名创建路由规则。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择自定义域名。
1. 在**路由详情**选项卡上，选择**添加路由规则**。
1. 选择**添加新条件**以添加新条件。
您可以添加标头或基本路径条件。要将所有传入的请求与自定义域名匹配，请不要添加条件。
1. 对于**操作**，使用下拉列表来选择目标 API 和目标阶段。
1. 选择**下一步**。
1. 在优先级字段中，为优先级输入一个数字。
API Gateway 按优先级顺序（从最低值到最高值）评估规则。
如果您创建的规则没有条件，我们建议您使用高值优先级。
1. 选择**创建路由规则**。
------
#### [ AWS CLI ]
以下 [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) 命令创建优先级为 50 的路由规则。在此示例中，API Gateway 将任何具有标头 `Hello:World` 和 `x-version:beta` 以及基本路径 `PetStoreShopper` 的传入请求路由到目标 API `a1b2c3`。
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
输出将与以下内容类似：
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## 更改路由规则的优先级
您可以更改路由规则的优先级。这将立即生效，并可能影响 API 使用者调用自定义域名的方式。我们建议您在设置路由规则的优先级时，在规则之间留出间隔。
例如，假设两个路由规则，规则 `abc123` 的优先级为 50，规则 `zzz000` 的优先级为 150。要更改规则的优先级，以便 API Gateway 首先评估 `zzz000` 规则，您可以将规则 `zzz000` 的优先级更改为 30。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择自定义域名。
1. 在**路由详情**选项卡上，选择路由规则，然后选择**编辑**。
1. 选择**下一步**。
1. 对于优先级，请输入新的优先级。
1. 选择**保存更改**。
------
#### [ AWS CLI ]
以下 [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html) 命令更改路由规则 `abc123` 的优先级。
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
输出将与以下内容类似：
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# 使用路由规则重新创建 API 映射
可以使用路由规则重新创建 API 映射。要重新创建 API 映射，请确保开启基本路径删除。这将保留 API 映射的行为。有关更多信息，请参阅 [使用基本路径条件删除基本路径](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split)。
以下教程展示了如何将 API 映射 `https:// api.example.com/orders/v2/items/categories/5` 重新创建为路由规则，以及如何更新访问日志以记录 API Gateway 用于向 API 发送流量的路由规则 ID。
------
#### [ AWS 管理控制台 ]
**将路由模式设置为 ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择自定义域名。
1. 对于**域详细信息**，选择**编辑**。
1. 对于**路由模式**，请选择 **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**。
1. 选择**保存**
设置路由模式后，可以创建路由规则。
**创建路由规则**
1. 在**路由详情**选项卡上，选择**添加路由规则**。
1. 选择**添加新条件**，然后选择**路径**。
1. 对于**路径**，输入 **orders/v2/items/categories/5**。
1. 对于**删除基本路径**，选择**活动**。
1. 对于**目标 API**，请选择目标 API。
1. 对于**目标阶段**，选择目标阶段。
1. 选择**下一步**。
1. 对于优先级，请输入优先级。
即使您保留现有的 API 映射，API Gateway 也将始终使用新的路由规则，因为路由规则始终优先于 API 映射。
1. 选择**保存更改**。
创建路由规则后，更新阶段的访问日志格式或创建新日志，以确认 API Gateway 使用路由规则来将流量发送到 API。
**更新访问日志**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择 API。
1. 在主导航窗格中，选择**阶段**。
1. 对于**日志和跟踪**，选择**编辑**。
如果您没有日志组，请参阅[为 API Gateway 中的 REST API 设置 CloudWatch 日志记录](set-up-logging.md)。
1. 将 **\$1context.customDomain.routingRuleIdMatched** 添加到您的日志格式。
此日志组记录 API Gateway 用来向 API 发送流量的路由规则 ID。有关更多信息，请参阅 [我不知道 API Gateway 是如何将流量发送到 API 的](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging)。
1. 选择 **Save**。
更新访问日志后，调用自定义域名。以下是一个示例 curl 命令，用于调用基本路径为 `orders/v2/items/categories/5` 的自定义域名 `https://api.example.com`。
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
成功调用自定义域名后，请确认 CloudWatch Logs 显示 `routingRuleIdMatched`。要了解如何使用 CloudWatch Logs 控制台来查看日志组，请参阅[在 CloudWatch 控制台中查看 API Gateway 日志事件](view-cloudwatch-log-events-in-cloudwatch-console.md)。
------
#### [ AWS CLI ]
1. 使用以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 命令更新域名 `api.example.com` 以使用路由模式 `ROUTING_RULE_THEN_API_MAPPING`。
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. 使用以下 [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) 命令创建新的路由规则，以重新创建 API 映射 `https://api.example.com/orders/v2/items/categories/5`。
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. 使用以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令更新访问日志格式以包含 `$context.customDomain.routingRuleIdMatched` 变量。此变量记录 API Gateway 用来向 API 发送流量的路由规则 ID。可以使用此日志来确认 API Gateway 是否使用路由规则将流量发送到 API。有关更多信息，请参阅 [我不知道 API Gateway 是如何将流量发送到 API 的](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging)。
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
如果您没有日志组，请参阅[为 API Gateway 中的 REST API 设置 CloudWatch 日志记录](set-up-logging.md)。
1. 使用以下示例 curl 命令来调用基本路径为 `orders/v2/items/categories/5` 的自定义域名。
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. 使用以下 [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html) 命令，来从日志组 `access-log-group-orders` 中获取包含路由规则 ID `abc123` 的日志事件。
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
这确认 API Gateway 已使用路由规则向 API 发送流量。
------
# 对路由规则相关问题进行故障排除
以下故障排除指南可能有助于解决与路由规则相关的问题。
## 我不知道 API Gateway 是如何将流量发送到 API 的
您可以使用 REST API 阶段的访问日志来记录路由规则并对其进行故障排除。您可以使用 `$context.customDomain.routingRuleIdMatched` 变量来查看 API Gateway 用于向 API 发送流量的路由规则 ID。要查看 API Gateway 用来向 API 发送流量的 API 映射，请使用 `$context.customDomain.basePathMatched` 变量。
要记录路由规则，您需要为您的账户配置[相应的 CloudWatch Logs 角色](set-up-logging.md#set-up-access-logging-permissions) ARN，然后创建一个日志组。
以下示例访问日志组可以检索相关信息，以便对路由规则和 API 映射进行故障排除。API Gateway 仅填充它使用的路由机制的上下文变量，否则上下文变量为 `-`。
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
我们还建议您确认自定义域名的路由模式。有关更多信息，请参阅 [为自定义域名设置路由模式](set-routing-mode.md)。
## 我无法对自定义域名启用路由规则
您可能会从 API Gateway 收到以下错误：
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
如果 IAM 策略拒绝访问 [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) 或 [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies)，您将收到此错误。当您为自定义域名启用路由规则时，尽管策略将继续拒绝访问 `BasePathMapping` 或 `ApiMapping`，但可以使用相同的策略来访问 `RoutingRule`。这可能支持用户更改自定义域名的路由行为。
例如，如果您有类似以下内容的策略：
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
当您为 `example.com` 启用路由规则时，此策略将继续拒绝旨在创建 `ApiMapping` 的访问，但不会拒绝旨在创建 `RoutingRule` 的访问。
我们建议您对账户中的 IAM 策略进行审计。以下示例策略将拒绝旨在创建 `ApiMapping`、`BasePathMapping` 和 `RoutingRule` 的访问：
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
确认所有策略都已更新后，您可以更新 API 的账户级设置，以便为区域启用路由规则。
使用以下 [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) 命令可针对区域更新 API 的账户级设置的设置：
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
更新 API 的账户级设置后，您可以更改自定义域名的路由模式。也可以继续使用 IAM 策略来拒绝访问 `RoutingRules`、`ApiMapping` 或 `BasePathMapping`。
# 使用 API 映射将 API 阶段连接到 REST API 的自定义域名
您可以使用 API 映射将 API 阶段连接到自定义域名。这样可以通过您的自定义域名将流量发送到 API。
API 映射指定了用于映射的 API、阶段以及可选的路径。例如，可以将 `https://api.example.com/orders` 映射到 API 的 `production` 阶段。
您可以将 HTTP 和 REST API 阶段映射到相同的自定义域名。
在创建 API 映射之前，您必须拥有 API、阶段和自定义域名。要了解有关创建自定义域名的更多信息，请参阅 [在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)。
## 针对自定义域名的传入请求
当您将自定义域名映射到 API 的某个阶段时，API Gateway 会删除传入的基本路径。这会移除从调用到 API 的映射基本路径。例如，如果基本路径映射是从 `https://api.example.com/orders/shop/5` 到 `test` 阶段，并且您使用了以下请求 `https://api.example.com/orders/shop/5/hats`，则 API Gateway 将调用 API 的 `test` 阶段的 `/hats` 资源，而不是 `orders/shop/5/hats` 资源。
## 映射 API 请求
以下内容解释 API Gateway 如何评估 API 映射。
可以使用单级映射创建 API 映射，例如从 `orders` 到 API 的 `beta` 阶段的 API 映射，以及从 `shipping` 到 API 的 `alpha` 阶段的 API 映射。对于采用 TLS 1.2 安全策略的区域自定义域名，API Gateway 支持多级 API 映射。可以创建从 `orders/v1/items` 到 API 的 `alpha` 阶段以及从 `orders/v2/items` 到 API 的 `beta` 阶段的 API 映射。当您创建具有多个级别的映射时，API Gateway 将请求发送到匹配路径最长的 API 映射。
可以创建到空路径 `(none)` 的 API 映射。如果没有任何路径与请求匹配，API Gateway 将请求发送到空路径 `(none)`。
在本例中，自定义域名 `https://api.example.com` 具有以下 API 映射。
| API 映射 | 选定的 API |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
下表显示了 API Gateway 如何将之前的 API 映射应用于示例请求。
| 请求 | 选定的 API | 说明 |
| --- | --- | --- |
| `https://api.example.com/orders` | API 2 | 请求完全匹配此 API 映射。 |
| `https://api.example.com/orders/v1/items` | API 3 | 请求完全匹配此 API 映射。 |
| `https://api.example.com/orders/v2/items` | API 4 | 请求完全匹配此 API 映射。 |
| `https://api.example.com/orders/v1/items/123` | API 3 | API Gateway 选择匹配路径最长的映射。请求结尾处的 `123` 不影响选择。请参阅[针对自定义域名的传入请求](#rest-api-mappings-incoming-requests)。 |
| `https://api.example.com/orders/v2/items/categories/5` | API 5 | API Gateway 选择匹配路径最长的映射。 |
| `https://api.example.com/customers` | API 1 | API Gateway 使用空映射作为“捕获全部”。 |
| `https://api.example.com/ordersandmore` | API 2 | API Gateway 选择匹配前缀最长的映射。 对于配置了单级映射的自定义域名（例如，仅 `https://api.example.com/orders` 和 `https://api.example.com/`），API Gateway 会选择 `API 1`，因为没有与 `ordersandmore` 匹配的路径。 |
## 限制
+ 在 API 映射中，自定义域名和映射的 API 必须位于同一个AWS账户中。
+ API 映射必须仅包含字母、数字和以下字符：`$-_.+!*'()/`。
+ API 映射中路径的最大长度为 300 个字符。
+ 每个域名可以有 200 个具有多个级别的 API 映射。此限制不包括单级的 API 映射，例如 `/prod`。
+ 您只能使用 TLS 1.2 安全策略将 HTTP API 映射到区域自定义域名。
+ 您不能将 WebSocket API 映射到与 HTTP API 或 REST API 相同的自定义域名。
+ 创建 API 映射后，您必须创建或更新 DNS 提供商的资源记录以映射到您的 API 端点。
+ 如果您创建具有多个级别的 API 映射，API Gateway 会将所有标头名称转换为小写。
## 创建 API 映射
要创建 API 映射，您必须首先创建自定义域名、API 和阶段。自定义域名的路由模式必须设置为 `ROUTING_RULE_THEN_API_MAPPING` 或 `API_MAPPING_ONLY`。有关如何设置路由模式的信息，请参阅[为自定义域名设置路由模式](set-routing-mode.md)。
例如，创建所有资源的 AWS Serverless Application Model 模板，请参阅 GitHub 上的[使用 SAM 的会话](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 从主导航窗格中选择**自定义域名**。
1. 选择自定义域名。
1. 在**路由详情**选项卡上，选择**配置 API 映射**。
1. 输入映射的 **API**、**阶段**和**路径**。
1. 选择**保存**。
------
#### [ AWS CLI ]
使用以下 [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) 命令创建 API 映射。在此示例中，API Gateway 将请求发送到 `api.example.com/v1/orders`，到指定的 API 和阶段。
**注意**
要创建具有多个级别的 API 映射，必须使用 `apigatewayv2`。
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
以下 CloudFormation 示例会创建一个 API 映射。
**注意**
要创建具有多个级别的 API 映射，必须使用 `AWS::ApiGatewayV2`。
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# API Gateway 中自定义域名的 IP 地址类型
当您创建自定义域名时，您指定可以调用域的 IP 地址的类型。可以选择 IPv4 以解析 IPv4 地址来调用域，也可以选择双堆栈以同时支持 IPv4 和 IPv6 地址调用域。我们建议您将 IP 地址类型设置为双堆栈，以缓解 IP 空间耗尽或保护您的安全状况。有关双堆栈 IP 地址类型的优势的更多信息，请参阅 [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)。
您可以通过更新域名的端点配置来更改 IP 地址类型。
## IP 地址类型的注意事项
以下注意事项可能会影响您对 IP 地址类型的使用。
+ 公有 API 的 API Gateway 自定义域名的默认 IP 地址类型是 IPv4。
+ 私有自定义域名只能具有双堆栈 IP 地址类型。
+ 对于映射到自定义域名的所有 API，自定义域名不需要具有相同的 IP 地址类型。如果您禁用默认 API 端点，则这可能会影响调用方调用域的方式。
## 更改自定义域名的 IP 地址类型
您可以通过更新域名的端点配置来更改 IP 地址类型。您可以使用 AWS 管理控制台、AWS CLI、CloudFormation 或 AWS SDK 更新端点配置。
------
#### [ AWS 管理控制台 ]
**更改自定义域名的 IP 地址类型**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择公有自定义域名。
1. 选择**端点配置**。
1. 对于 IP 地址类型，选择 **IPv4** 或**双堆栈**。
1. 选择**保存**。
------
#### [ AWS CLI ]
以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令将 API 更新为具有双堆栈 IP 地址类型：
```
aws apigateway update-domain-name \
--domain-name dualstack.example.com \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
输出将与以下内容类似：
```
{
"domainName": "dualstack.example.com",
"certificateUploadDate": "2025-02-04T14:46:10-08:00",
"regionalDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"regionalHostedZoneId": "Z3LQWSYCGH4ADY",
"regionalCertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"tags": {}
}
```
------
# 选择针对 API Gateway 中自定义域的安全策略
*安全策略* 是 API Gateway 提供的最低 TLS 版本和密码套件的预定义组合。当您的客户端与您的 API 或自定义域名建立 TLS 握手时，安全策略会强制实施 API Gateway 接受的 TLS 版本和密码套件。安全策略会保护您的 API 和自定义域名免受网络安全问题的侵扰，例如客户端和服务器之间的篡改和侦听。
API Gateway 支持传统安全策略和增强型安全策略。`TLS_1_0` 和 `TLS_1_2` 是传统安全策略。将这些安全策略用于通用工作负载，或者开始创建 API。任何以 `SecurityPolicy_` 开头的策略都是增强型安全策略。可将这些策略用于受监管的工作负载、高级治理或后量子密码术。使用增强型安全策略时，还必须设置端点访问模式以进行更多治理。有关更多信息，请参阅 [端点访问模式](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)。
## 注意事项
以下是 API Gateway 中针对 REST API 自定义域名的安全策略的注意事项：
+ 您无法对使用增强型安全策略的域名启用双向 TLS。
+ 您无法将 HTTP API 映射到使用增强型安全策略的域名。
+ 如果为使用增强型安全策略的 REST API 启用多级基础路径映射，则无法为同一域名创建指向 HTTP API 的基础路径映射。
+ 您的 API 可以映射到与 API 具有不同安全策略的自定义域名。当您调用该自定义域名时，API Gateway 会使用 API 的安全策略来协商 TLS 握手。如果您禁用默认 API 端点，则这可能会影响调用方调用 API 的方式。
+ API Gateway 支持对所有 API 应用安全策略。但是，您只能为 REST API 选择安全策略。对于 HTTP 或 WebSocket API，API Gateway 仅支持 `TLS_1_2` 安全策略。
+ API Gateway 不支持为具有多种端点类型的域名更新安全策略。如果域名有多种端点类型，请删除其中一个以更新安全策略。
## API Gateway 如何应用安全策略
以下示例以 `SecurityPolicy_TLS13_1_3_2025_09` 安全策略为例，显示 API Gateway 如何应用安全策略。
`SecurityPolicy_TLS13_1_3_2025_09` 安全策略接受 TLS 1.3 流量并拒绝 TLS 1.2 和 TLS 1.0 流量。对于 TLS 1.3 流量，该安全策略接受以下密码套件：
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway 不接受任何其他密码套件。例如，该安全策略将拒绝使用 `AES128-SHA` 密码套件的任何 TLS 1.3 流量。
要监控客户端使用哪些 TLS 协议和密码来访问您的 API Gateway，您可以在访问日志中使用 `$context.tlsVersion` 和 `$context.cipherSuite` 上下文变量。有关更多信息，请参阅 [监控 API Gateway 中的 REST API](rest-api-monitor.md)。
要查看所有 REST API 和自定义域名的默认安全策略，请参阅[默认安全策略](apigateway-security-policies-list.md#apigateway-security-policies-default)。要查看所有 REST API 和自定义域名支持的安全策略，请参阅[支持的安全策略](apigateway-security-policies-list.md)。
## 更改您的自定义域名的安全策略
如果您更改安全策略，大约需要 15 分钟才能完成更新。您可以监控自定义域名的 `lastUpdateStatus`。当您的自定义域名更新时，`lastUpdateStatus` 为 `PENDING`，更新完成后，它将变为 `AVAILABLE`。
当您使用以 `SecurityPolicy_` 开头的安全策略时，还必须打开端点访问模式。有关更多信息，请参阅 [端点访问模式](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)。
------
#### [ AWS 管理控制台 ]
**更改自定义域名的安全策略**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择将流量发送到 REST API 的自定义域名。
确保只有一种端点类型与您的自定义域名关联。
1. 选择**自定义域名设置**，然后选择**编辑**。
1. 对于**安全策略**，选择一个新策略。
1. 对于**端点访问模式**，请选择**严格**。
1. 选择**保存更改**。
------
#### [ AWS CLI ]
以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令将域名更新为使用 `SecurityPolicy_TLS13_1_3_2025_09` 安全策略：
```
aws apigateway update-domain-name \
--domain-name example.com \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
输出将与以下内容类似：
```
{
"domainName": "example.com",
"endpointConfiguration": {
"types": [ "REGIONAL" ],
"ipAddressType": "dualstack"
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
}
```
------
## 有关 HTTP API 和 WebSocket API 的信息
有关 HTTP API 和 WebSocket API 的更多信息，请参阅[API Gateway 中的 HTTP API 的安全策略](http-api-ciphers.md)和[针对 API Gateway 中的 WebSocket API 的安全策略](websocket-api-ciphers.md)。
# 禁用 REST API 的默认端点
默认情况下，客户端可以通过使用 API Gateway 为 API 生成的 `execute-api` 端点来调用您的 API。为确保客户端只能通过使用自定义域名访问您的 API，请禁用默认 `execute-api` 端点。客户端仍然可以连接到您的默认端点，但它们会收到 `403 Forbidden` 状态码。禁用默认端点会影响 API 的所有阶段。当您更新任何阶段上的任何设置（例如，更新阶段上的部署）时，此设置就会生效。
以下过程说明了如何禁用 REST API 的默认端点。
------
#### [ AWS 管理控制台 ]
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 在主导航窗格中，选择 **API 设置**。
1. 选择一个 API。
1. 在 **API 详细信息**选项卡上，选择**编辑**。
1. 对于**默认端点**，选择**非活动**。
1. 选择**保存更改**。
1. 在主导航窗格中，选择**资源**。
1. 选择**部署 API**。
1. 将 API 重新部署到阶段或更新阶段上的任何设置，以使更新生效。
------
#### [ AWS CLI ]
使用以下 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 命令禁用默认端点：
```
aws apigateway update-rest-api \
--rest-api-id abcdef123 \
--patch-operations op=replace,path=/disableExecuteApiEndpoint,value='True'
```
禁用默认端点后，必须部署 API 才能使更改生效。
以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建部署并将其与某个阶段关联：
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name dev
```
------
# 为 API Gateway API 配置针对 DNS 故障转移的自定义运行状况检查
您可以使用 Amazon Route 53 运行状况检查，来控制从主要 AWS 区域的 API Gateway API 到辅助区域的 API Gateway API 的 DNS 故障转移。这可以帮助减轻在出现区域性问题时的影响。如果您使用自定义域，则无需客户端更改 API 终端节点，即可执行故障转移。
当您为别名记录选择[评估目标运行状况](https://docs.aws.amazon.com/Route53/latest/APIReference/API_AliasTarget.html#Route53-Type-AliasTarget-EvaluateTargetHealth>Evaluate Target Health)时，只有当 API Gateway 服务在该区域不可用时，这些记录才会失败。某些情况下，您自己的 API Gateway API 可能会在此之前遇到中断。要直接控制 DNS 故障转移，请为您的 API Gateway API 配置自定义 Route 53 运行状况检查。在本示例中，您使用 CloudWatch 警报来帮助操作员控制 DNS 故障转移。有关配置故障转移的更多示例和其他注意事项，请参阅[使用 Route 53 创建灾难恢复机制](https://aws.amazon.com/blogs/networking-and-content-delivery/creating-disaster-recovery-mechanisms-using-amazon-route-53/)和[使用 AWS Lambda 和 CloudWatch 对 VPC 中的私有资源执行 Route 53 运行状况检查](https://aws.amazon.com/blogs/networking-and-content-delivery/performing-route-53-health-checks-on-private-resources-in-a-vpc-with-aws-lambda-and-amazon-cloudwatch/)。
**Topics**
+ [先决条件](#dns-failover-prereqs)
+ [步骤 1：设置资源](#dns-failover-intial-setup)
+ [步骤 2：启动到辅助区域的故障转移](#dns-failover-initiate)
+ [步骤 3：测试故障转移](#dns-failover-test)
+ [步骤 4：返回主区域](#dns-failover-return)
+ [后续步骤：自定义和定期测试](#dns-failover-next-steps)
## 先决条件
要完成此过程，您必须创建和配置以下资源：
+ 您拥有的域名。
+ 该域名在两个 AWS 区域中的 ACM 证书。有关更多信息，请参阅[自定义域名的先决条件](how-to-custom-domains.md#how-to-custom-domains-prerequisites)。
+ 您的域名的 Route 53 托管区域。有关更多信息，请参阅《Amazon Route 53 开发人员指南》中的[使用托管区域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html)。
有关如何为域名创建 Route 53 失效转移 DNS 记录的更多信息，请参阅《Amazon Route 53 开发人员指南》中的[选择路由策略](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html)。有关如何监控 CloudWatch 警报的更多信息，请参阅《Amazon Route 53 开发人员指南》中的[监控 CloudWatch 警报](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html#health-checks-creating-values-cloudwatch)。
## 步骤 1：设置资源
在此示例中，您将创建以下资源来为您的域名配置 DNS 故障转移：
+ 两个 AWS 区域中的 API Gateway API
+ 两个 AWS 区域中同名的 API Gateway 自定义域名
+ 将您的 API Gateway API 连接到自定义域名的 API Gateway API 映射
+ 域名的 Route 53 故障转移 DNS 记录
+ 辅助区域的 CloudWatch 警报
+ 在辅助区域进行的基于 CloudWatch 警报的 Route 53 运行状况检查
首先，确保您的主区域和辅助区域都拥有所有必需的资源。辅助区域应包含警报和运行状况检查。这样，您无需依赖主区域即可进行故障转移。有关创建这些资源的 CloudFormation 模板示例，请参阅[samples/primary.zip](samples/primary.zip)和[samples/secondary.zip](samples/secondary.zip)。
**重要**
在故障转移到辅助区域之前，请确保所有必需的资源都可用。否则，您的 API 将无法为辅助区域的流量做好准备。
## 步骤 2：启动到辅助区域的故障转移
在以下示例中，备用区域收到 CloudWatch 指标并启动故障转移。我们使用需要操作员干预才能启动故障转移的自定义指标。
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 1 \
--region us-west-1
```
将指标数据替换为您配置的 CloudWatch 警报的相应数据。
## 步骤 3：测试故障转移
调用您的 API 并验证您是否收到辅助区域的响应。如果您在步骤 1 中使用了示例模板，则故障转移后，响应将从 `{"message": "Hello from the primary Region!"}` 更改为 `{"message": "Hello from the secondary Region!"}`。
```
curl https://my-api.example.com
{"message": "Hello from the secondary Region!"}
```
## 步骤 4：返回主区域
要返回主区域，请发送使运行状况检查顺利通过的 CloudWatch 指标。
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 0 \
--region us-west-1
```
将指标数据替换为您配置的 CloudWatch 警报的相应数据。
调用您的 API 并验证您是否收到主区域的响应。如果您在步骤 1 中使用了示例模板，则响应将从 `{"message": "Hello from the secondary Region!"}` 更改为 `{"message": "Hello from the primary Region!"}`。
```
curl https://my-api.example.com
{"message": "Hello from the primary Region!"}
```
## 后续步骤：自定义和定期测试
此示例演示了一种配置 DNS 故障转移的方法。您可以使用各种 CloudWatch 指标或 HTTP 终端节点进行运行状况检查，以管理故障转移。定期测试您的故障转移机制，确保它们按预期运行，并且操作员熟悉您的故障转移过程。