# 发布 REST API 供客户调用
仅仅创建和开发 API Gateway API 并不会自动使其可供用户调用。要使 API 可供调用，您必须将其部署到一个阶段。此外，建议您自定义用户将用于访问 API 的 URL。您可以为其提供一个与品牌一致的域，或者使其比 API 的默认 URL 更容易记住。
在本节中，您可以了解如何部署 API 并自定义您提供给用户以访问 API 的 URL。
**注意**
为了增强您的 API Gateway API 的安全性，将在[公共后缀列表 (PSL)](https://publicsuffix.org/) 中注册 `execute-api.{region}.amazonaws.com` 域。为进一步增强安全性，如果您需要在 API Gateway API 的默认域名中设置敏感 Cookie，我们建议您使用带 `__Host-` 前缀的 Cookie。这将有助于保护您的域，防范跨站点请求伪造 (CSRF) 攻击。要了解更多信息，请参阅 Mozilla 开发者网络中的 [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) 页面。
**Topics**
+ [在 API Gateway 中部署 REST API。](how-to-deploy-api.md)
+ [API Gateway 中公共 REST API 的自定义域名](how-to-custom-domains.md)
# 在 API Gateway 中部署 REST API。
创建 API 之后，您必须对其进行部署，以便您的用户可以调用它。
要部署 API，您可以创建 API 部署并将其与阶段关联。一个阶段是对您 API 生命周期状态（例如，`dev`、`prod`、`beta`、`v2`）的一次逻辑引用。API 阶段由 API ID 和阶段名称标识。它们包含在您用于调用 API 的 URL 中。每个阶段都是一个对 API 部署的命名引用，可供客户端应用程序调用。
**重要**
每次更新 API 时，您都必须将 API 重新部署到现有阶段或新阶段。更新 API 涉及修改路由、方法、集成、授权方、资源策略以及除阶段设置之外的任何其他内容。
随着 API 的发展，您可以继续将其作为 API 的不同版本部署到不同阶段。您还可以将 API 更新部署为 [Canary 版本部署](canary-release.md)。这使您的 API 客户端可在相同阶段上，通过生产版本访问正式版本，并通过 Canary 版本访问更新的版本。
为调用已部署 API，客户端对 API 的 URL 提交请求。URL 由 API 的协议（HTTP(S) 或 (WSS)）、主机名、阶段名称和（对于 REST API）资源路径确定。主机名和阶段名称确定 API 的基本 URL。
使用 API 的默认域名，给定阶段 (`{stageName}`) 中的 REST API 的基本 URL（例如）采用以下格式：
```
https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName}
```
要使 API 的默认基本 URL 对用户更友好，您可以创建自定义域名（例如 `api.example.com`）来替换该 API 的默认主机名。要支持自定义域名下的多个 API，您必须将 API 阶段映射到基本路径。
使用自定义域名 `{api.example.com}`，以及在自定义域名下映射到基本路径 (`{basePath}`) 的 API 阶段，REST API 的基本 URL 将如下所示：
```
https://{api.example.com}/{basePath}
```
对于每个阶段，您可以通过调整默认账户级别请求限制并启用 API 缓存来优化 API 性能。您还可以启用对 CloudTrail 或 CloudWatch 的 API 调用的日志记录，并为后端选择客户端证书以对 API 请求进行身份验证。此外，您也可以覆盖各个方法的阶段级别设置并定义阶段变量，以便在运行时将特定于阶段的环境上下文传递到 API 集成中。
阶段实现了对 API 的可靠版本控制。例如，您可以将 API 部署到 `test` 阶段和 `prod` 阶段，并使用 `test` 阶段作为测试版本，使用 `prod` 阶段作为稳定版本。更新通过测试之后，您可以将 `test` 阶段提升到 `prod` 阶段。可以通过将 API 重新部署到 `prod` 阶段或者将阶段变量值从 `test` 的阶段名称更新为 `prod` 的阶段名称来完成提升。
在本部分中，我们讨论如何使用 [API Gateway 控制台](https://console.aws.amazon.com/apigateway)或调用 [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/) 来部署 API。要使用其他工具，请参阅[AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) 的文档或者[AWS开发工具包](https://aws.amazon.com/developer/tools/#sdk)。
**Topics**
+ [为 API Gateway 中的 REST API 创建部署](set-up-deployments.md)
+ [为 API Gateway 中的 REST API 设置阶段](set-up-stages.md)
+ [设置 API Gateway Canary 版本部署](canary-release.md)
+ [对需要重新部署的 REST API 的更新](updating-api.md)
# 为 API Gateway 中的 REST API 创建部署
在 API Gateway 中，以[部署](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html)资源来表示REST API 部署。它类似于由 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源表示的 API 的可执行文件。
要让客户端调用 API，您必须创建部署并将阶段与其关联。阶段由[阶段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)资源表示。它代表 API 的快照，包括方法、集成、模型、映射模板、Lambda 授权方（以前称为自定义授权方）。更新 API 时，您可以通过将新阶段与现有部署关联来重新部署 API。我们在[为 API Gateway 中的 REST API 设置阶段](set-up-stages.md)中介绍了创建阶段。
**Topics**
+ [创建 部署。](#create-deployment)
+ [API 部署的后续步骤](#apigateway-deployment-next-steps)
## 创建 部署。
以下过程说明如何为 REST API 创建部署。
------
#### [ AWS 管理控制台 ]
您必须先创建 REST API，然后才能对其进行首次部署。有关更多信息，请参阅 [开发 API Gateway 中的 REST API](rest-api-develop.md)。
借助 API Gateway 控制台，您可以创建部署并将其与新的或现有阶段相关联，从而部署 API。
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在 **APIs** 导航窗格中，选择您要部署的 API。
1. 在**资源**窗格中，选择 **Deploy API (部署 API)**。
1. 对于**阶段**，请从以下选项中进行选择：
1. 要创建新阶段，请选择**新建阶段**，然后在**阶段名称**中输入名称。或者，您可以在**部署描述**中为部署提供描述。
1. 要选择现有阶段，请从下拉菜单中选择阶段名称。您可能需要在**部署描述**中为新部署提供描述。
1. 要创建没有与阶段关联的部署，请选择**没有阶段**。稍后，您可以将此部署与阶段相关联。
1. 选择**部署**。
------
#### [ AWS CLI ]
创建部署时，您实例化[部署](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html)资源。
使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建新部署。
```
aws apigateway create-deployment --rest-api-id rest-api-id
```
在将此部署与阶段关联之后，您才能调用 API。对于现有阶段，您可以使用新创建的部署 ID 来更新阶段的 [deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) 属性，从而完成此操作。以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令使用新部署更新阶段：在控制台中，这被称为**活跃部署**。
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name 'stage-name' \
--patch-operations op='replace',path='/deploymentId',value='deployment-id'
```
在您创建部署时，还可以同时将部署与新阶段关联。以下 [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建新部署并将其与名为 `beta` 的阶段关联：
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name beta
```
------
要重新部署 API，请执行相同的步骤。您可以重用同一个阶段。
## API 部署的后续步骤
以下是 API 部署的后续步骤。
修改阶段设置
部署完 API 后，您可以修改阶段设置，以启用或禁用 API 缓存、日志记录或请求限制。您还可以为后端选择客户端证书以对 API Gateway 进行身份验证，并设置阶段变量，从而在运行时将部署上下文传递至 API 集成。有关更多信息，请参阅 [修改阶段设置](set-up-stages.md#how-to-stage-settings)
修改阶段设置后，您必须重新部署 API 才能使更改生效。
如果启用日志记录等更新的设置要求使用新的 IAM 角色，您无需重新部署 API 即可添加所需的 IAM 角色。但是，新的 IAM 角色可能需要几分钟才能生效。在该角色生效之前，即使您已启用日志记录选项，系统也不会记录对 API 调用的跟踪。
选择不同的部署阶段组合
由于部署代表 API 快照，而阶段可定义到快照的路径，因此您可以选择不同的部署阶段组合，以控制用户如何调用不同版本的 API。这非常有用，例如，如果您想将 API 状态回滚至上一个部署，或者将 API 的“私有分支”合并到公有分支中，就可以这样做。
以下过程介绍如何在 API Gateway 控制台中使用**阶段编辑器**执行此操作。我们假定您已多次部署 API。
1. 如果您尚未打开**阶段**窗格，请在主导航窗格中选择**阶段**。
1. 选择要更新的阶段。
1. 在**部署历史记录**选项卡上，选择您希望阶段使用的部署。
1. 选择**更改活动部署**。
1. 确认要更改活动部署，然后在**设为活动部署**对话框中，选择**更改活动部署**。
将特定于部署的数据传递给您的 API。
对于部署，您可以设置或修改阶段变量，从而在运行时将特定于部署的数据传递至 API 集成。您可以在 **Stage Editor (阶段编辑器)** 中的 **Stage Variables (阶段变量)** 选项卡上执行此操作。有关更多信息，请参阅[在 API Gateway 中对 REST API 使用阶段变量](stage-variables.md)中的说明。
# 为 API Gateway 中的 REST API 设置阶段
阶段是对某个部署的指定引用，是 API 的快照。您可以使用[阶段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)来管理和优化特定的部署。例如，您可以配置阶段设置，以便启用缓存、自定义请求限制、配置日志记录、定义阶段变量或者附加 Canary 版本进行测试。以下部分介绍如何创建和配置阶段。
## 创建新阶段
初始部署后，您可以添加更多阶段，并将它们与现有部署进行关联。在部署 API 时，您可以使用 API Gateway 控制台来创建新阶段或选择现有阶段。一般来说，重新部署 API 之前，您可以向 API 部署中添加新阶段。要使用 API Gateway 控制台创建新阶段，请按照下列步骤操作：
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 在主导航窗格中，选择某个 API 下的**阶段**。
1. 从**阶段**导航窗格中，选择**创建阶段**。
1. 对于**阶段名称**，请输入名称，例如 **prod**。
**注意**
阶段名称只能包含字母数字字符、连字符和下划线。最大长度为 128 个字符。
1. （可选）。对于**描述**，请输入阶段描述。
1. 从**部署**中，选择要与此阶段关联的现有 API 部署的日期和时间。
1. 在**其它设置**下，您可以为阶段指定其它设置。
1. 选择**创建阶段**。
## 修改阶段设置
成功部署 API 后，系统将使用默认设置填充阶段。您可以使用控制台或 API Gateway REST API 更改阶段设置，包括 API 缓存和日志记录。如果您修改了 REST API 的默认端点，则在更新阶段时，修改会传播到 API 的所有阶段。以下步骤说明如何使用 API Gateway 控制台的**阶段编辑器**来执行这一操作。
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 在主导航窗格中，选择某个 API 下的**阶段**。
1. 在**阶段**窗格中，选择该阶段的名称。
1. 在**阶段详细信息**部分中，选择**编辑**。
1. （可选）对于**阶段描述**，输入描述。
1. 对于**其他设置**，修改以下设置：
**缓存设置**
要为阶段启用 API 缓存，请开启**配置 API 缓存**。然后，配置**默认方法级缓存**、**缓存容量**、**加密缓存数据**、**缓存生存时间(TTL)**，以及每个密钥缓存失效的任何要求。
在开启默认方法级缓存或为特定方法开启方法级缓存之前，缓存不会处于活动状态。
有关缓存设置的更多信息，请参阅 [API Gateway 中针对 REST API 的缓存设置](api-gateway-caching.md)。
如果您为 API 阶段启用 API 缓存，系统可能会针对 API 缓存向您的 AWS 账户收费。缓存没有资格享受 AWS 免费套餐。
**节流设置**
要为与该 API 相关联的所有方法设置阶段级别节流目标，请开启**节流**。
针对**比率**部分，请输入目标率。这是将令牌添加到令牌桶的频率，以每秒请求数计。阶段级别频率不得超过[API Gateway 中用于配置和运行 REST API 的配额](api-gateway-execution-service-limits-table.md)中规定的[账户级别](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits)频率。
针对**突增**部分，请输入目标突增率。突增频率是令牌桶的容量。这允许在一段时间内通过比目标速率更多的请求。该阶段级别突增率不得超过在 [API Gateway 中用于配置和运行 REST API 的配额](api-gateway-execution-service-limits-table.md) 中指定的[账户级别](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits)突增比率。
节流费率不是硬限制，应基于最佳效果来应用。在某些情况下，客户端可能会超过您设置的目标。不要依靠使用节流来控制成本或阻止对 API 的访问。考虑使用 [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) 监控成本和 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) 来管理 API 请求。
**防火墙和证书设置**
要将 AWS WAF Web ACL 与阶段关联，请从 **Web ACL** 下拉列表中选择一个 Web ACL。如果需要，请选择**如果无法评估 WebACL，则阻止 API 请求(失败 - 关闭)**。
要为您的阶段选择客户端证书，请从**客户端证书**下拉菜单中选择证书。
1. 选择**继续**。
1. 预览更改，然后选择**保存更改**。
1. 要为与此 API Gateway API 的此阶段相关联的所有方法启用 Amazon CloudWatch Logs，请在**日志和跟踪**部分选择**编辑**。
**注意**
要启用 CloudWatch Logs，您还必须指定 IAM 角色的 ARN，该角色使 API Gateway 能够代表您的用户将信息写入 CloudWatch Logs。为此，请从 **APIs** 主导航窗格中选择**设置**。然后，对于 **CloudWatch 日志角色**，输入 IAM 角色的 ARN。
对于常见的应用程序场景，IAM 角色可以附加 [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) 的托管策略。
IAM 角色还必须包含以下信任关系语句：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
有关 CloudWatch 的更多信息，请参阅 *[Amazon CloudWatch 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*。
1. 从 **CloudWatch Logs** 下拉菜单中选择日志记录级别。日志记录级别如下所示：
+ **关闭** - 不对此阶段开启日志记录。
+ **仅限错误** - 仅对错误启用日志记录。
+ **错误和信息日志** - 对所有事件启用日志记录。
1. 选择**数据跟踪**，让 API Gateway 向 CloudWatch 报告阶段的数据跟踪日志记录。这对于排除 API 故障非常有用，但可能会导致记录敏感数据。
**注意**
建议不要为生产 API 启用**数据跟踪**。
1. 选择**详细指标**，让 API Gateway 向 CloudWatch 报告 `API calls`、`Latency`、`Integration latency`、`400 errors` 和 `500 errors` 的 API 指标。有关 CloudWatch 的更多信息，请参阅《Amazon CloudWatch 用户指南》中的[基本监控和详细监控](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html)。
**重要**
我们将针对访问方法级别 CloudWatch 指标而非 API 级或存储级指标向您的账户收费。
1. 要启用对目标的访问日志记录，请打开**自定义访问日志记录**。
1. 对于**访问日志目标 ARN**，输入日志组或 Firehose 流的 ARN。
Firehose 的 ARN 格式为 `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`。Firehose 流的名称必须为 `amazon-apigateway-{your-stream-name}`。
1. 在**日志格式**中，输入日志格式。要了解有关示例日志格式的更多信息，请参阅[用于 API Gateway 的 CloudWatch 日志格式](set-up-logging.md#apigateway-cloudwatch-log-formats)。
1. 要为 API 阶段启用 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) 跟踪，请选择 **X-Ray 跟踪**。有关更多信息，请参阅 [在 API Gateway 中使用 X-Ray 跟踪用户对 REST API 的请求](apigateway-xray.md)。
1. 选择**保存更改**。重新部署 API 以使新设置生效。
## 覆盖阶段级别设置
自定义阶段级别设置后，可以为每个 API 方法覆盖这些设置。其中一些选项可能会导致您的 AWS 账户产生额外费用。
1. 要配置方法覆盖，请在二级导航窗格下展开阶段，然后选择一种方法。
![\[在二级导航窗格下展开阶段，然后选择一种方法。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/method-override-view-new-console.png)
1. 对于**方法覆盖**，选择**编辑**。
1. 要开启方法级别 CloudWatch 设置，请为 **CloudWatch Logs** 选择一个日志记录级别。
1. 要为您的方法启用数据跟踪日志记录，请选择**数据跟踪**。
**注意**
建议不要为生产 API 启用**数据跟踪**。
1. 要开启方法级别详细指标，请选择**详细指标**。我们将针对访问方法级别 CloudWatch 指标而非 API 级或存储级指标向您的账户收费。
1. 要开启方法级别的节流，请选择**节流**。输入适合的方法级别选项。要了解有关节流的更多信息，请参阅 [在 API Gateway 中限制对 REST API 的请求以提高吞吐量](api-gateway-request-throttling.md)。
1. 要配置方法级别缓存，请选择**启用方法缓存**。如果您在**阶段详细信息**中更改默认方法级缓存设置，它不会影响此设置。
1. 选择**保存**。
# 添加 API Gateway REST API 作为 Amazon Bedrock AgentCore 网关的目标
Amazon Bedrock AgentCore 网关为人工智能代理开发人员提供了一种安全的方式，可以将您的 API Gateway REST API 作为与模型上下文协议（MCP）兼容的工具公开。AgentCore 网关使用目标来定义工具。当您将阶段添加为目标时，您的网关将变成单个 MCP URL，使代理能够访问这些工具。有关更多信息，请参阅《Amazon Bedrock AgentCore 网关开发人员指南》**中的 [API Gateway REST API 阶段作为目标](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html)。
API Gateway 目标将您的 AgentCore 网关连接到 REST API 的各个阶段。您可以将整个阶段作为目标，也可以选择资源。在您创建 API Gateway 目标后，AgentCore 网关会将传入的 MCP 请求转换为 HTTP 请求并处理响应格式。MCP 客户端可以使用 `tools/list` 方法检索 API 文档，并使用 `tools/call` 方法调用 API。
## 注意事项
以下注意事项可能会影响您将阶段作为目标添加到 AgentCore 网关：
+ 您必须已经有 AgentCore 网关。
+ 仅支持公共 REST API。
+ 无法禁用 API 的默认端点。
+ API 的每个方法都必须为其定义[操作名称](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html#apigw-PutMethod-request-operationName)，或者您在将阶段添加为目标时需要创建名称覆盖。此名称用作代理用来与您的方法进行交互的工具名称。
+ 您可以使用 `API_KEY`、`NO_AUTH` 或 `GATEWAY_IAM_ROLE` 凭证提供程序类型进行出站身份验证，以允许您的网关访问您的 API。`API_KEY` 凭证提供程序由 AgentCore 网关定义。您可以使用现有的 API Gateway API 密钥。有关更多信息，请参阅[设置出站身份验证](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html)。
+ 如果使用 Amazon Cognito 用户池或 Lambda Authorizer 来控制对 API 的访问权限，MCP 客户端将无法访问 API。
+ 您的 API 必须与您的 AgentCore 网关位于同一账户和区域。
## 将 API 的阶段添加为 AgentCore 网关的目标
以下过程说明如何将 API 的阶段添加为 AgentCore 网关的目标。
**将 API 的阶段添加为 AgentCore 网关的目标**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择已部署到某个阶段的 REST API。
1. 在主导航窗格中，选择**阶段**。
1. 选择**阶段操作**，然后选择**创建 MCP 目标**。
1. 对于 **AgentCore 网关**，请选择 AgentCore 网关。
1. 对于**目标名称**，请输入目标名称。
1. 对于**目标描述**，请输入描述。
1. 保留提供的 API 和阶段。
1. 对于**选择 API 资源**，请选择使用您的 AgentCore 网关的代理可以访问的 API 资源。
如果您不选择资源，代理将无法查看文档或调用端点。
1. 资源和方法的组合是该工具的操作。如果您的操作没有名称，请创建一个名称覆盖。
您还可以在创建方法时为其定义操作名称。
1. 对于**出站身份验证配置**，请选择 **IAM 角色**、**无授权**或 **API 密钥**。
1. 选择**创建目标**。
要查看有权访问您的 API 的所有 AgentCore 网关，请在主导航窗格中选择 **MCP 目标**部分。在此部分中，您可以为您所在区域中部署到某个阶段的任何 API 创建 MCP 目标。选择**创建 MCP 目标**，然后按照前面的步骤操作。
您还可以在 AgentCore 网关控制台中查看目标的可用工具并编辑目标。有关更多信息，请参阅[向现有 AgentCore 网关添加目标](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html)。
# 删除阶段
当您不再需要某个阶段时，可以将其删除，以免为未使用的资源付费。以下步骤介绍如何使用 API Gateway 控制台删除阶段。
**警告**
删除阶段可能会导致 API 调用方无法使用部分或全部相应的 API。删除阶段无法撤销，但您可以重新创建阶段并将其与相同的部署相关联。
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 在主导航窗格中，选择**阶段**。
1. 在**阶段**窗格中，选择您要删除的阶段，然后依次选择**阶段操作**和**删除阶段**。
1. 当系统提示您时，输入 **confirm**，然后选择**删除**。
# 为 API Gateway 中的 API 阶段设置标签
在 API Gateway 中，您可以将标签添加到 API 阶段、从阶段中删除标签或者查看标签。为此，您可以使用 API Gateway 控制台、AWS CLI/开发工具包或 API Gateway REST API。
阶段还可以从其父 REST API 继承标签。有关更多信息，请参阅 [Amazon API Gateway V1 API 中的标签继承](apigateway-tagging-supported-resources.md#apigateway-tagging-inheritance)。
有关标记 API Gateway 资源的更多信息，请参阅 [为 API Gateway 资源添加标签](apigateway-tagging.md)。
**Topics**
+ [使用 API Gateway 控制台为 API 阶段设置标签](#set-up-tags-using-console)
+ [使用 AWS CLI 为 API 阶段设置标签](#set-up-tags-using-cli)
+ [使用 API Gateway REST API 为 API 阶段设置标签](#set-up-tags-using-api)
## 使用 API Gateway 控制台为 API 阶段设置标签
以下过程将介绍如何为 API 阶段设置标签。
**使用 API Gateway 控制台为 API 阶段设置标签**
1. 登录 API Gateway 控制台。
1. 选择一个现有 API，或者创建包括资源、方法和对应集成的新 API。
1. 选择阶段或者将 API 部署到新阶段。
1. 在主导航窗格中，选择**阶段**。
1. 选择**标签**选项卡。您可能需要选择右箭头按钮以显示该选项卡。
1. 选择**管理标签**。
1. 在**标签编辑器**中，选择**添加标签**。在**键**字段中输入标签键（例如 `Department`），在**值**字段中输入标签值（例如 `Sales`）。选择**保存**以保存标签。
1. 如果需要，请重复第 5 步，将更多标签添加到 API 阶段。每个阶段的最大标签数是 50。
1. 要从阶段中移除现有标签，请选择**移除**。
1. 如果先前已在 API Gateway 控制台中部署了 API，则需要重新进行部署，以使更改生效。
## 使用 AWS CLI 为 API 阶段设置标签
您可以使用 AWS CLI，通过 [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) 命令或 [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) 命令为 API 阶段设置标签。您可以使用 [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) 命令从 API 阶段中删除一个或多个标签。
使用以下 [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) 命令在创建 `test` 阶段时添加一个标签：
```
aws apigateway create-stage --rest-api-id abc1234 --stage-name test --description 'Testing stage' --deployment-id efg456 --tag Department=Sales
```
使用以下 [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) 命令将标签添加到 `prod` 阶段中：
```
aws apigateway tag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/prod --tags Department=Sales
```
使用以下 [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) 命令从 `test` 阶段中删除 `Department=Sales` 标签：
```
aws apigateway untag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/test --tag-keys Department
```
## 使用 API Gateway REST API 为 API 阶段设置标签
您可以执行以下操作之一，使用 API Gateway REST API 为 API 阶段设置标签：
+ 调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) 为 API 阶段添加标签。
+ 调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) 以从 API 阶段中删除一个或多个标签。
+ 调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) 以将一个或多个标签添加到您正创建的 API 阶段。
您还可以调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) 以描述 API 阶段中的标签。
### 为 API 阶段添加标签
将 API (`m5zr3vnks7`) 部署到阶段 (`test`) 之后，通过调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) 为阶段添加标签。所需的阶段 Amazon Resource Name (ARN) (`arn:aws:apigateway:us-east-1::/restapis/m5zr3vnks7/stages/test`) 必须为 URL 编码 (`arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest`)。
```
PUT /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest
{
"tags" : {
"Department" : "Sales"
}
}
```
您还可以使用之前的请求，将现有标签更新为新值。
在调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) 创建阶段时，您可以将标签添加到阶段。
```
POST /restapis//stages
{
"stageName" : "test",
"deploymentId" : "adr134",
"description" : "test deployment",
"cacheClusterEnabled" : "true",
"cacheClusterSize" : "500",
"variables" : {
"sv1" : "val1"
},
"documentationVersion" : "test",
"tags" : {
"Department" : "Sales",
"Division" : "Retail"
}
}
```
### 取消 API 阶段的标签
要从阶段中删除 `Department` 标签，请调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html)：
```
DELETE /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest?tagKeys=Department
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
要删除多个标签，请在查询表达式中使用逗号分隔的标签键列表，例如 `?tagKeys=Department,Division,…`。
### 描述 API 阶段的标签
要描述指定阶段上的现有标签，请调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html)：
```
GET /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
成功响应的形式与下方类似：
```
200 OK
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-tags-{rel}.html",
"name": "tags",
"templated": true
},
"tags:tag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags"
},
"tags:untag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags{?tagKeys}",
"templated": true
}
},
"tags": {
"Department": "Sales"
}
}
```
# 在 API Gateway 中对 REST API 使用阶段变量
阶段变量是可以定义为与 REST API 部署阶段关联的配置属性的键-值对。它们与环境变量的功能类似，可用于 API 设置和映射模板。利用 API Gateway 中的部署阶段，可以管理每个 API 的多个发布阶段；利用阶段变量，您可以将 API 部署阶段配置为与不同的后端端点进行交互。
阶段变量不适用于敏感数据，例如凭证。要将敏感数据传递给集成，请使用 AWS Lambda 授权方。您可以在 Lambda 授权方的输出中将敏感数据传递给集成。要了解更多信息，请参阅“[来自 API Gateway Lambda 授权方的输出](api-gateway-lambda-authorizer-output.md)”。
## 阶段变量的使用案例
以下是阶段变量的使用案例。
**指定其他后端端点**
您的 API 可以将 `GET` 请求作为 HTTP 代理传递给后端 Web 主机。您可以使用阶段变量，以使得在 API 调用方调用生产端点时，API Gateway 调用 `example.com`。之后，当 API 调用方调用 beta 阶段时，API Gateway 会调用其他 Web 主机，例如 `beta.example.com`。同样，阶段变量可用于为 API 中的每个阶段指定不同的 AWS Lambda 函数名称。您不能使用阶段变量来设置其他集成端点，例如，在一个阶段将 `GET` 请求指向 HTTP 代理集成，并在另一个阶段将该请求指向 Lambda 代理集成。
将 Lambda 函数名称指定为阶段变量值时，您必须手动配置对 Lambda 函数的权限。当您在 API Gateway 控制台中指定 Lambda 函数时，将弹出一条 AWS CLI 命令，让您配置正确的权限。您也可以使用以下 AWS CLI 命令来执行此操作。
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**使用映射模板传递信息**
您还可以访问映射模板中的阶段变量，或者将配置参数传递给 AWS Lambda 或 HTTP 后端。例如，您可能需要针对 API 中的多个阶段重复使用同一个 Lambda 函数，但是该函数应根据阶段，从不同的 Amazon DynamoDB 表中读取数据。在为 Lambda 函数生成请求的映射模板中，您可以使用阶段变量来将表的名称传递给 Lambda。
要使用阶段变量，首先要配置阶段变量，然后为其分配值。例如，要自定义 HTTP 集成端点，请先创建 `url` 阶段变量，然后在 API 的集成请求中输入阶段变量值 **http://\$1\$1stageVariables.url\$1**。此值将指示 API Gateway 在运行时替换您的阶段变量 `${}`，具体取决于 API 正在哪个阶段运行。有关更多信息，请参阅[为 API Gateway 中的 REST API 设置阶段变量](how-to-set-stage-variables-aws-console.md)。
# 为 API Gateway 中的 REST API 设置阶段变量
此部分介绍如何使用 Amazon API Gateway 控制台为示例 API 的两个部署阶段设置阶段变量。要了解如何在 API Gateway 中使用阶段变量，建议您按照此部分中的所有过程进行操作。
## 先决条件
在您开始之前，确保您满足以下先决条件：
+ API Gateway 中必须有可用的 API。按照中的说明进行操作[开发 API Gateway 中的 REST API](rest-api-develop.md)
+ 您必须至少部署过一次 API。按照中的说明进行操作[在 API Gateway 中部署 REST API。](how-to-deploy-api.md)
+ 您必须为已部署的 API 创建了第一个阶段。按照中的说明进行操作[创建新阶段](set-up-stages.md#how-to-create-stage-console)
## 使用阶段变量通过 API 调用 HTTP 端点
此过程介绍如何为 HTTP 端点创建阶段变量以及如何为 API 创建两个阶段。此外，您可以创建在此部分的以下过程中使用的阶段变量 `url`、`stageName` 和 `function`。
**使用阶段变量通过 API 调用 HTTP 端点**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 创建 API，然后在 API 的根资源上创建 `GET` 方法。将集成类型设置为 **HTTP**，并将**端点 URL** 设置为 **http://\$1\$1stageVariables.url\$1**。
1. 将 API 部署到名为 **beta** 的新阶段。
1. 在主导航窗格中，选择**阶段**，然后选择 **beta** 阶段。
1. 在**阶段变量**选项卡上，选择**编辑**。
1. 选择**添加阶段变量**。
1. 对于**名称**，请输入 **url**。对于**值**，输入 **httpbin.org/get**。
1. 选择**添加阶段变量**，然后执行以下操作：
对于**名称**，请输入 **stageName**。对于**值**，输入 **beta**。
1. 选择**添加阶段变量**，然后执行以下操作：
对于**名称**，请输入 **function**。对于**值**，输入 **HelloWorld**。
1. 选择**保存**。
1. 现在创建第二个阶段。从**阶段**导航窗格中，选择**创建阶段**。对于**阶段名称**，输入 **prod**。从**部署**中选择一个新近部署，然后选择**创建阶段**。
1. 与 **beta** 阶段一样，将相同的三个阶段变量（**url**、**stageName** 和 **function**）分别设置为不同的值（**petstore-demo-endpoint.execute-api.com/petstore/pets**、**prod** 和 **HelloEveryone**）。
1. 在**阶段**导航窗格中，选择 **beta** 阶段。在**阶段详细信息**下，选择复制图标以复制 API 的调用 URL，然后在 Web 浏览器中输入 API 的调用 URL。这将启动 API 根资源上的 **beta** 阶段 `GET` 请求。
**注意**
**Invoke URL** 链接指向 API 在其 **beta** 阶段的根资源。在 Web 浏览器中输入 URL 会对根资源调用 **beta** 阶段 `GET` 方法。如果方法是在子资源而非根资源本身上定义的，则在 Web 浏览器中输入 URL 将返回 `{"message":"Missing Authentication Token"}` 错误响应。在这种情况下，您必须将特定子资源的名称附加到**调用 URL** 链接。
1. **beta** 阶段 `GET` 请求的响应如下所示。您还可以使用浏览器导航到 **http://httpbin.org/get**，以验证结果。此值已分配到 **beta** 阶段中的 `url` 变量。这两个响应完全相同。
1. 在**阶段**导航窗格中，选择 **prod** 阶段。在**阶段详细信息**下，选择复制图标以复制 API 的调用 URL，然后在 Web 浏览器中输入 API 的调用 URL。这将启动 API 根资源上的 **prod** 阶段 `GET` 请求。
1. **prod** 阶段 `GET` 请求的响应如下所示。您可以使用浏览器导航到 **http://petstore-demo-endpoint.execute-api.com/petstore/pets**，以验证结果。此值已分配到 **prod** 阶段中的 `url` 变量。这两个响应完全相同。
## 将特定于阶段的元数据传入 HTTP 后端
此过程介绍如何在查询参数表达式中使用阶段变量值将特定于阶段的元数据传递到 HTTP 后端。我们将使用上一个过程中声明的 `stageName` 阶段变量。
**将特定于阶段的元数据传入 HTTP 后端**
1. 在**资源**导航窗格中，选择 **GET** 方法。
要向方法的 URL 添加查询字符串参数，请选择**方法请求**选项卡，然后在**方法请求设置**部分中选择**编辑**。
1. 选择 **URL 查询字符串参数**并执行以下操作：
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **stageName**。
1. 保持**必填**和**缓存**为已关闭状态。
1. 选择**保存**。
1. 选择**集成请求**选项卡，然后在**集成请求设置**部分中，选择**编辑**。
1. 对于**端点 URL**，将 **?stageName=\$1\$1stageVariables.stageName\$1** 附加到先前定义的 URL 值，因此整个**端点 URL** 为 **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**。
1. 选择**部署 API**，然后选择 **beta** 阶段。
1. 在主导航窗格中，选择**阶段**。在**阶段**导航窗格中，选择 **beta** 阶段。在**阶段详细信息**下，选择复制图标以复制 API 的调用 URL，然后在 Web 浏览器中输入 API 的调用 URL。
**注意**
我们之所以在这里使用测试阶段，是因为 HTTP 端点（由 `url` 变量“http://httpbin.org/get”指定）接受查询参数表达式，并在响应中将其作为 `args` 对象返回。
1. 您将收到以下响应。注意，分配给 `beta` 阶段变量的 `stageName` 作为 `stageName` 参数传递到后端。
![\[使用 url 阶段变量通过 HTTP 端点从 API 的 GET 方法获取响应。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## 使用阶段变量通过 API 调用 Lambda 函数
此过程介绍了如何使用阶段变量调用 Lambda 函数作为 API 后端。您使用已在[使用阶段变量通过 API 调用 HTTP 端点](#how-to-set-stage-variables-aws-console-http-endpoint)中声明的 `function` 阶段变量。
在将 Lambda 函数设置为阶段变量的值时，请使用函数的本地名称，可能包括其别名或版本规范，例如 **HelloWorld**、**HelloWorld:1** 或 **HelloWorld:alpha**。请勿使用该函数的 ARN（例如 **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**）。API Gateway 控制台将 Lambda 函数的阶段变量值假定为非限定的函数名称，并且会将给定的阶段变量扩展到 ARN 中。
**使用阶段变量通过 API 调用 Lambda 函数**
1. 使用默认 Node.js 运行时系统创建名为 **HelloWorld** 的 Lambda 函数。代码必须包含以下内容：
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
有关如何创建 Lambda 函数的更多信息，请参阅 [REST API 控制台入门](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function)。
1. 在**资源**窗格中，选择**创建资源**，然后执行以下操作：
1. 对于**资源路径**，选择 **/**。
1. 对于**资源名称**，输入 **lambdav1**。
1. 选择**创建资源**。
1. 选择 **/lambdav1** 资源，然后选择**创建方法**。
然后执行以下操作：
1. 对于**方法类型**，选择 **GET**。
1. 对于**集成类型**，选择 **Lambda 函数**。
1. 保持 **Lambda 代理集成**处于关闭状态。
1. 对于 **Lambda 函数**，输入 `${stageVariables.function}`。
![\[按照 function 阶段变量指定的方式，创建与 Lambda 函数集成的 GET 方法。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**提示**
当提示使用**添加权限命令**时，复制 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 命令。对将分配给 `function` 阶段变量的每个 Lambda 函数运行此命令。例如，如果 `$stageVariables.function` 值为 `HelloWorld`，则运行以下 AWS CLI 命令：
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
否则会导致在调用该方法时出现 `500 Internal Server Error` 响应。将 `${stageVariables.function}` 替换为已分配给阶段变量的 Lambda 函数名称。
![\[AWS CLI 命令，以便添加针对要由您创建的方法调用的 Lambda 函数的权限。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. 选择**创建方法**。
1. 将 API 部署到 **prod** 和 **beta** 阶段。
1. 在主导航窗格中，选择**阶段**。在**阶段**导航窗格中，选择 **beta** 阶段。在**阶段详细信息**下，选择复制图标以复制 API 的调用 URL，然后在 Web 浏览器中输入 API 的调用 URL。在按 Enter 之前，将 **/lambdav1** 附加到 URL。
您将收到以下响应。
```
"Hello, World! I'm not sure where I'm calling from..."
```
## 通过阶段变量将特定于阶段的元数据传递到 Lambda 函数中
此过程介绍了如何使用阶段变量将特定于阶段的配置元数据传递到 Lambda 函数中。您创建 `POST` 方法和输入映射模板，以使用先前声明的 `stageName` 阶段变量生成负载。
**通过阶段变量将特定于阶段的元数据传递到 Lambda 函数中**
1. 选择 **/lambdav1** 资源，然后选择**创建方法**。
然后执行以下操作：
1. 对于**方法类型**，选择 **POST**。
1. 对于**集成类型**，选择 **Lambda 函数**。
1. 保持 **Lambda 代理集成**处于关闭状态。
1. 对于 **Lambda 函数**，输入 `${stageVariables.function}`。
1. 当提示使用**添加权限命令**时，复制 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 命令。对将分配给 `function` 阶段变量的每个 Lambda 函数运行此命令。
1. 选择**创建方法**。
1. 选择**集成请求**选项卡，然后在**集成请求设置**部分中，选择**编辑**。
1. 选择**映射模板**，然后选择**添加映射模板**。
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下模板：
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**注意**
在映射模板中，阶段变量必须在引号中引用（如 `"$stageVariables.stageName"` 或 `"${stageVariables.stageName}"` 中所示）。在其他位置，必须不带引号引用（如 `${stageVariables.function}` 中所示）。
1. 选择**保存**。
1. 将 API 部署到 **beta** 和 **prod** 阶段。
1. 要使用 REST API 客户端传递特定于阶段的元数据，请执行以下操作：
1. 在**阶段**导航窗格中，选择 **beta** 阶段。在**阶段详细信息**下，选择复制图标以复制 API 的调用 URL，然后在 REST API 客户端的输入字段中输入 API 的调用 URL。在提交请求之前附加 **/lambdav1**。
您将收到以下响应。
```
"Hello, World! I'm calling from the beta stage."
```
1. 在**阶段**导航窗格中，选择 **prod**。在**阶段详细信息**下，选择复制图标以复制 API 的调用 URL，然后在 REST API 客户端的输入字段中输入 API 的调用 URL。在提交请求之前附加 **/lambdav1**。
您将收到以下响应。
```
"Hello, World! I'm calling from the prod stage."
```
1. 要使用**测试**特征传递特定于阶段的元数据，请执行以下操作：
1. 在**资源**导航窗格中，选择**测试**选项卡。您可能需要选择右箭头按钮以显示该选项卡。
1. 对于 **function**，请输入 **HelloWorld**。
1. 对于 **stageName**，请输入 **beta**。
1. 选择**测试**。您无需将正文添加到您的 `POST` 请求。
您将收到以下响应。
```
"Hello, World! I'm calling from the beta stage."
```
1. 您可以重复前面的步骤来测试 **Prod** 阶段。对于 **stageName**，请输入 **Prod**。
您将收到以下响应。
```
"Hello, World! I'm calling from the prod stage."
```
# API Gateway 中的 REST API 的 API Gateway 阶段变量引用
在以下情况下，您可以使用 API Gateway 阶段变量。
## 参数映射表达式
阶段变量可在参数映射表达式中用于 API 方法的请求或响应标头参数，无需进行任何部分替换。在以下示例中，引用阶段变量时未使用 `$` 和封闭的 `{...}`。
+ `stageVariables.`
## 映射模板
阶段变量可在映射模板中的任何位置使用，如以下示例所示。
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## HTTP 集成 URI
阶段变量可用作 HTTP 集成 URL 的一部分，如以下示例所示：
+ 不带协议的完整 URI – `http://${stageVariables.}`
+ 完整域 – `http://${stageVariables.}/resource/operation`
+ 子域 – `http://${stageVariables.}.example.com/resource/operation`
+ 路径 – `http://example.com/${stageVariables.}/bar`
+ 查询字符串 – `http://example.com/foo?q=${stageVariables.}`
## AWS 集成 URI
阶段变量可用作 AWS URI 操作或路径组件的一部分，如以下示例所示。
+ `arn:aws:apigateway:::${stageVariables.}`
## AWS 集成 URI（Lambda 函数）
阶段变量可用于替代 Lambda 函数名称或版本/别名，如以下示例所示。
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**注意**
要将阶段变量用于 Lambda 函数，该函数必须与 API 位于同一账户中。阶段变量不支持跨账户 Lambda 函数。
## Amazon Cognito 用户池
阶段变量可用来代替 `COGNITO_USER_POOLS` 授权方的 Amazon Cognito 用户池。
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWS 集成凭证
阶段变量可用作 AWS 用户/角色凭证 ARN 的一部分，如以下示例所示。
+ `arn:aws:iam:::${stageVariables.}`
# 设置 API Gateway Canary 版本部署
[Canary 版本](https://martinfowler.com/bliki/CanaryRelease.html)是一种软件开发战略，部署新版本的 API（以及其他软件）用于测试，而在相同阶段基础版本仍部署为生产版本用于正常运营。在本文档中，为了方便讨论，我们将基础版本称为生产版本。虽然这样做是合理的，您也可以随意在任意非生产版本上应用 Canary 版本进行测试。
在 Canary 版本部署中，全部 API 流量按照预配置的比率，随机拆分到生产版本和 Canary 版本中。通常，Canary 版本接收少量百分比的 API 流量，生产版本接受剩余部分。更新后的 API 特征仅对流经 Canary 的 API 流量可见。您可以调整 Canary 流量百分比来优化测试覆盖范围或性能。
通过将 Canary 流量保持在较小的比例并随机进行选择，大部分用户在任何时间都不会受到新版本中潜在错误的不利影响，而且没有任何一个用户会始终受到不利影响。
在测试指标满足您的要求之后，可以将金丝雀版本提升为生产版本，并在部署中禁用 Canary 版本。这使得新特征在生产阶段中可用。
**Topics**
+ [API Gateway 中的 Canary 版本部署](#api-gateway-canary-release-deployment-overview)
+ [创建 Canary 版本部署](create-canary-deployment.md)
+ [更新 Canary 版本](update-canary-deployment.md)
+ [提升 Canary 版本](promote-canary-deployment.md)
+ [关闭金丝雀版本](delete-canary-deployment.md)
## API Gateway 中的 Canary 版本部署
在 API Gateway 中，Canary 版本部署将部署阶段用于 API 基础版本的生产版本，并将 Canary 版本连接到阶段，用于提供 API 相对于基础版本的新版本。该阶段与初始部署关联，Canary 与后续部署关联。在一开始，阶段和 Canary 均指向相同的 API 版本。在这一部分中，我们所说的阶段和生产版本是可以互换的，Canary 和 Canary 版本也是可以互换的。
要部署带有 Canary 版本的 API，您必须将 [Canary 设置](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings)添加到常规[部署](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html)的[阶段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)。Canary 设置描述基本金丝雀版本，阶段表示此部署中 API 的生产版本。要添加 Canary 设置，请在部署阶段上设置 `canarySettings` 并指定以下内容：
+ 部署 ID，最初与阶段上设置的基础版本部署的 ID 相同。
+ Canary 版本的 [API 流量百分比](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic)，在 0.0 到 100.0（含）之间。
+ [Canary 版本的阶段变量](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides)，可以覆盖生产版本阶段变量。
+ 为 Canary 版本请求[使用的阶段缓存](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache)（如果设置了 [useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) 并在阶段上启用了 API 缓存）。
启用 Canary 版本之后，除非禁用 Canary 版本并从阶段中删除 Canary 设置，否则部署阶段无法与其他非 Canary 版本部署关联。
当您启用 API 执行日志记录时，Canary 版本为所有 Canary 请求生成自己的日志和指标。它们报告给生产阶段 CloudWatch Logs 日志组，以及 Canary 版本特定的 CloudWatch Logs 日志组。访问日志记录也是如此。单独的 Canary 特定日志非常有用，可用于验证新 API 更改以及决定是否接受更改并将 Canary 版本提升为生产版本，或者放弃更改并从生产阶段还原 Canary 版本。
生产阶段执行日志组名为 `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}`，Canary 版本执行日志组名为 `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary`。对于访问日志记录，您必须创建新日志组或者选择现有日志组。Canary 版本访问日志组名称具有 `/Canary` 后缀，附加到选定的日志组名中。
Canary 发布可以使用阶段缓存（如果启用），并在预定义的生存时间 (TTL) 周期内，使用缓存的条目将结果返回到下一个 Canary 发布请求。
在 Canary 版本部署中，API 的生产版本和 Canary 版本可以关联到同一个版本，也可以关联到不同版本。当它们与不同版本关联时，来自生产和 Canary 请求的响应单独缓存，阶段缓存返回生产和 Canary 请求的对应结果。当生产版本和 Canary 版本关联到同一个部署时，阶段缓存为两种类型的请求使用单个缓存键，并为来自生产版本和 Canary 版本的相同请求返回相同响应。
# 创建 Canary 版本部署
在部署具有 [Canary 设置](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings)的 API 作为对[部署创建](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html)操作的额外输入时，您可以创建 Canary 版本部署。
您还可以通过发出 [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) 请求在阶段上添加 Canary 版本设置，从现有非 Canary 版本部署创建 Canary 版本。
创建非 Canary 版本部署时，您可以指定非现有阶段名称。如果指定的阶段不存在，API Gateway 将创建一个。但是，在创建 Canary 版本部署时，您无法指定任何非现有阶段名称。您会收到错误，并且 API Gateway 不创建任何 Canary 版本部署。
您可以使用 API Gateway 控制台、AWS CLI 或AWS开发工具包在 API Gateway 中创建 Canary 版本部署。
**Topics**
+ [使用 API Gateway 控制台创建 Canary 版本部署](#create-canary-deployment-using-console)
+ [使用 AWS CLI 创建 Canary 版本部署](#create-canary-deployment-using-cli)
## 使用 API Gateway 控制台创建 Canary 版本部署
要使用 API Gateway 控制台创建 Canary 版本部署，请按照以下说明操作：
**创建初始 Canary 版本部署**
1. 登录 API Gateway 控制台。
1. 选择现有 REST API 或创建新的 REST API。
1. 在主导航窗格中，选择**资源**，然后选择**部署 API**。按照 **Deploy API (部署 API)** 中屏幕上的说明操作，将 API 部署到新阶段。
到目前为止，您已将 API 部署到生产版本阶段。接下来，您需要在阶段上配置 Canary 设置，并且在需要时还要启用缓存、设置阶段变量或者配置 API 执行或访问日志。
1. 要启用 API 缓存或将 AWS WAF Web ACL 与阶段关联，请在**阶段详细信息**部分中选择**编辑**。有关更多信息，请参阅[API Gateway 中针对 REST API 的缓存设置](api-gateway-caching.md)或[使用 API Gateway 控制台将 AWS WAF Web ACL 与 API Gateway API 阶段相关联](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console)。
1. 要配置执行或访问日志记录，请在**日志和跟踪**部分中选择**编辑**，并按照屏幕上的说明操作。有关更多信息，请参阅[为 API Gateway 中的 REST API 设置 CloudWatch 日志记录](set-up-logging.md)。
1. 要设置阶段变量，请选择**阶段变量**选项卡，并按照屏幕上的说明添加或修改阶段变量。有关更多信息，请参阅[在 API Gateway 中对 REST API 使用阶段变量](stage-variables.md)。
1. 选择**金丝雀**选项卡，然后选择**创建金丝雀**。您可能需要选择右箭头按钮以显示**金丝雀**选项卡。
1. 在**金丝雀设置**下，对于**金丝雀**，输入要转移到金丝雀的请求的百分比。
1. 如果需要，请选择**阶段缓存**以便为金丝雀版本开启缓存。除非启用 API 缓存，否则缓存对 Canary 版本不可用。
1. 要覆盖现有的阶段变量，对于**金丝雀覆盖**，请输入新的阶段变量值。
在部署阶段上初始化 Canary 版本之后，您更改了 API 并希望测试更改。您可以将 API 重新部署到相同阶段，这样可以通过同一个阶段访问更新后的版本和基础版本。以下步骤说明了如何完成此操作。
**将最新 API 版本部署到 Canary**
1. 每次更新 API 时，请选择**部署 API**。
1. 在**部署 API** 中，从**部署阶段**下拉列表中选择包含金丝雀的阶段。
1. （可选）为**部署描述**输入描述。
1. 选择 **Deploy (部署)** 将最新 API 版本推送到 Canary 版本。
1. 如果需要，可重新配置阶段设置、日志或 Canary 设置，如[创建初始 Canary 版本部署](#to-create-canary-release-on-new-deployment)中所述。
此时，Canary 版本指向最新版本，而生产版本仍指向 API 的初始版本。[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 现在具有新的 **deploymentId** 值，而阶段仍具有最初的 [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) 值。在后台，控制台调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html)。
## 使用 AWS CLI 创建 Canary 版本部署
**为新阶段创建金丝雀部署**
1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建具有两个阶段变量但没有金丝雀的部署：
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
输出将与以下内容类似：
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令，在 `prod` 阶段上创建金丝雀部署：
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
输出将与以下内容类似：
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
生成的部署 `id` 标识 Canary 版本的 API 测试版本。此时关联的阶段启用了 Canary。
1. （可选）使用以下 [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) 命令查看阶段表示：
```
aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod
```
下面说明了以命令输出表示的 `Stage`：
```
{
"stageName": "prod",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "du4ot1",
"lastUpdatedDate": 1511379433,
"createdDate": 1511379050,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "a6rox0",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
在本例中，API 的基础版本将使用阶段变量 `{"sv0":val0", "sv1":val1"}`，而测试版本使用阶段变量 `{"sv1":val2", "sv2":val3"}`。生产版本和 Canary 版本均使用相同的阶段变量 `sv1`，但分别具有不同值 `val1` 和 `val2`。阶段变量 `sv0` 仅用于生产版本中，阶段变量 `sv2` 仅用于 Canary 版本中。
您还可通过更新阶段来启用金丝雀，从现有常规部署创建金丝雀版本部署。
**从现有部署创建金丝雀版本部署**
1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建没有金丝雀的部署：
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. 使用 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令更新阶段以启用金丝雀：
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name 'beta' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
输出将与以下内容类似：
```
{
"stageName": "beta",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "cifeiw",
"lastUpdatedDate": 1511381930,
"createdDate": 1511380879,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "cifeiw",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
由于您在 API 的现有版本上启用了金丝雀，生产版本（`Stage`）和金丝雀版本（`canarySettings`）指向了相同的部署。在您更改 API 并将其再次部署到此阶段之后，新版本将为 Canary 版本，而基础版本保持为生产版本。在阶段演变中，Canary 的 `deploymentId` 更新为新部署 `id`，而生产版本的 `deploymentId` 保持不变，证明了这一点。
# 更新 Canary 版本
在部署了 Canary 版本之后，您可能需要调整 Canary 流量的百分比，或者启用或禁用阶段缓存以优化测试性能。在更新执行上下文时，您还可以修改在 Canary 版本中使用的阶段变量。要进行此类更新，请在 [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 上使用新值调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) 操作。
您可以使用 API Gateway 控制台、AWS CLI [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令或AWS开发工具包更新 Canary 版本。
**Topics**
+ [使用 API Gateway 控制台更新 Canary 版本](#update-canary-deployment-using-console)
+ [使用 AWS CLI 更新 Canary 版本](#update-canary-deployment-using-cli)
## 使用 API Gateway 控制台更新 Canary 版本
要使用 API Gateway 控制台更新阶段上的现有 Canary 设置，请执行以下操作：
**更新现有的金丝雀设置**
1. 登录 API Gateway 控制台并选择现有的 REST API。
1. 在主导航窗格中，选择**阶段**，然后选择一个现有阶段。
1. 选择**金丝雀**选项卡，然后选择**编辑**。您可能需要选择右箭头按钮以显示**金丝雀**选项卡。
1. 通过在 0.0 到 100.0 之间（含）增加或减少百分比数字，更新**请求分布**。
1. 选中或清除**阶段缓存**复选框。
1. 添加、移除或修改**金丝雀阶段变量**。
1. 选择**保存**。
## 使用 AWS CLI 更新 Canary 版本
要使用 AWS CLI 更新金丝雀，请使用 [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令，修改金丝雀的每个参数的补丁操作。
以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令更新金丝雀是否使用阶段缓存：
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/useStageCache,value=true
```
以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令更新金丝雀流量百分比：
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0
```
以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 更新阶段变量。示例演示如何创建名为的 `newVar` 的新阶段变量，覆盖 `var2` 阶段变量，然后删除 `var1` 阶段变量：
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/var2",
"value": "val4"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}]'
```
您可以通过将操作组合到单个 `patch-operations` 值中，更新以上所有内容。
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/percentTraffic",
"value": "20.0"
}, {
"op": "replace",
"path": "/canarySettings/useStageCache",
"value": "true"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/val2",
"value": "val4"
}]'
```
# 提升 Canary 版本
当您提升金丝雀版本时，金丝雀版本会取代当前的阶段设置。提升 Canary 版本不会在阶段上禁用 Canary。要禁用 Canary，您必须在阶段上删除 Canary 设置。要提升金丝雀版本，请执行以下操作：
+ 使用 Canary 的[部署 ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 设置重置阶段的[部署 ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId)。这会使用 Canary 的快照更新阶段的 API 快照，使得测试版本也成为生产版本。
+ 使用 Canary 阶段变量更新阶段变量（如有）。这会使用 Canary 的内容更新阶段的 API 执行上下文。没有此更新时，如果测试版本使用不同的阶段变量或者现有阶段变量的不同值，新 API 版本可能会造成意外的结果。
+ 将 Canary 流量的百分比设置为 0.0%。
**Topics**
+ [使用 API Gateway 控制台提升 Canary 版本](#promote-canary-release-deployment-console)
+ [使用 AWS CLI 提升 Canary 版本](#promote-canary-release-cli)
## 使用 API Gateway 控制台提升 Canary 版本
要使用 API Gateway 控制台提升 Canary 版本部署，请执行以下步骤：
**提升金丝雀版本部署**
1. 登录 API Gateway 控制台并在主导航窗格中选择现有 API。
1. 在主导航窗格中，选择**阶段**，然后选择一个现有阶段。
1. 选择**金丝雀**选项卡。
1. 选择**提升金丝雀**。
1. 确认所做的更改，然后选择**提升金丝雀**。
提升之后，生产版本引用相同的 API 版本 (**deploymentId**) 作为 Canary 版本。您可以使用 AWS CLI 验证此项。有关示例，请查看[使用 AWS CLI 提升 Canary 版本](#promote-canary-release-cli)。
## 使用 AWS CLI 提升 Canary 版本
要使用 AWS CLI 命令将 Canary 版本提升到生产版本，请调用 `update-stage` 命令以将与 Canary 版本关联的 `deploymentId` 复制到与阶段关联的 `deploymentId`，将 Canary 版本流量百分比重置为零 (`0.0`)，并且将任意 Canary 版本绑定阶段变量复制到对应的阶段绑定变量。
假设我们有一个 Canary 版本部署，由类似于以下内容的阶段描述：
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 10.5
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "nfcn0x",
"lastUpdatedDate": "2017-11-22T00:54:28Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv1": "val1"
}
}
```
使用以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令提升金丝雀：
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
输出将与以下内容类似：
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 0
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "eh1sby",
"lastUpdatedDate": "2017-11-22T05:29:47Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv2": "val3",
"sv1": "val2"
}
}
```
将金丝雀版本提升到阶段并不会禁用该金丝雀版本，部署仍然是金丝雀版本部署。要使其成为常规生产版本部署，您必须禁用 Canary 设置。有关如何禁用 Canary 版本部署的更多信息，请参阅 [关闭金丝雀版本](delete-canary-deployment.md)。
# 关闭金丝雀版本
要关闭金丝雀版本部署，请将 [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 设置为 Null 以从阶段中删除它。
您可以使用 API Gateway 控制台、AWS CLI 或AWS开发工具包禁用 Canary 版本部署。
**Topics**
+ [使用 API Gateway 控制台关闭金丝雀版本](#delete-canary-release-console)
+ [使用 AWS CLI 关闭金丝雀版本](#delete-canary-release-cli)
## 使用 API Gateway 控制台关闭金丝雀版本
要使用 API Gateway 控制台关闭金丝雀版本部署，请执行以下步骤：
**关闭金丝雀版本部署**
1. 登录 API Gateway 控制台并在主导航窗格中选择现有 API。
1. 在主导航窗格中，选择**阶段**，然后选择一个现有阶段。
1. 选择**金丝雀**选项卡。
1. 选择**删除**。
1. 选择 **Delete (删除)** 确认您要删除 Canary。
结果，[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 属性变为 `null`，并从部署[阶段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)中删除。您可以使用 AWS CLI 验证此项。有关示例，请查看[使用 AWS CLI 关闭金丝雀版本](#delete-canary-release-cli)。
## 使用 AWS CLI 关闭金丝雀版本
以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令关闭金丝雀版本部署：
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name canary \
--patch-operations '[{"op":"remove", "path":"/canarySettings"}]'
```
输出内容如下所示：
```
{
"stageName": "prod",
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "nfcn0x",
"lastUpdatedDate": 1511309280,
"createdDate": 1511152939,
"methodSettings": {
...
}
}
```
如输出中所示，在禁用了金丝雀的部署中，[stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) 中不再有 [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 属性。
# 对需要重新部署的 REST API 的更新
维护 API 相当于查看、更新和删除现有的 API 设置。可以使用 API Gateway 控制台、AWS CLI、CloudFormation、SDK 或 API Gateway REST API 来维护 API。更新 API 涉及到修改 API 的特定资源属性或配置设置。资源更新需要重新部署 API，而配置更新不需要。
下表描述了 API 资源，在更新这些 API 资源时需要重新部署 API。
| 资源 | 备注 |
| --- | --- |
| [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) | 有关适用的属性和支持的操作，请参阅 [apikey:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateApiKey.html)。此更新需要重新部署 API。 |
| [授权方](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 有关适用的属性和支持的操作，请参阅 [authorizer:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAuthorizer.html)。此更新需要重新部署 API。 |
| [disableExecuteApiEndpoint](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html#apigw-UpdateRestApi-response-disableExecuteApiEndpoint) | 更新要求修改 API 上的任何阶段，例如将 API 重新部署到阶段。 |
| [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) | 有关适用的属性和支持的操作，请参阅 [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html)。此更新需要重新部署 API。 |
| [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) | 有关适用的属性和支持的操作，请参阅 [documentationversion:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationVersion.html)。此更新需要重新部署 API。 |
| [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) | 有关适用的属性和支持的操作，请参阅 [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html#remarks)。此更新需要重新部署 API。 |
| [集成](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | 有关适用的属性和支持的操作，请参阅 [integration:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegration.html)。此更新需要重新部署 API。 |
| [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) | 有关适用的属性和支持的操作，请参阅 [integrationresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegrationResponse.html)。此更新需要重新部署 API。 |
| [ 方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 有关适用的属性和支持的操作，请参阅 [method:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html)。此更新需要重新部署 API。 |
| [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) | 有关适用的属性和支持的操作，请参阅 [methodresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethodResponse.html)。此更新需要重新部署 API。 |
| [模型](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 有关适用的属性和支持的操作，请参阅 [model:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateModel.html)。此更新需要重新部署 API。 |
| [RequestValidator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) | 有关适用的属性和支持的操作，请参阅 [requestvalidator:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRequestValidator.html)。此更新需要重新部署 API。 |
| [资源](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 有关适用的属性和支持的操作，请参阅 [resource:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)。此更新需要重新部署 API。 |
| [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) | 有关适用的属性和支持的操作，请参阅 [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html)。此更新需要重新部署 API。这包括修改资源策略。 |
| [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) | 有关适用的属性和支持的操作，请参阅 [vpclink:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateVpcLink.html)。此更新需要重新部署 API。 |
下表描述了 API 配置，在更新这些 API 配置时步需要重新部署 API。
| 配置 | 备注 |
| --- | --- |
| [Account](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html) | 有关适用的属性和支持的操作，请参阅 [account:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html)。此更新不需要重新部署 API。 |
| [部署](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) | 有关适用的属性和支持的操作，请参阅 [deployment:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDeployment.html)。 |
| [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) | 有关适用的属性和支持的操作，请参阅 [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html)。此更新不需要重新部署 API。 |
| [BasePathMapping](https://docs.aws.amazon.com/apigateway/latest/api/API_BasePathMapping.html) | 有关适用的属性和支持的操作，请参阅 [basepathmapping:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateBasePathMapping.html)。此更新不需要重新部署 API。 |
| [IP 地址类型](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateRestApi.html) | 此更新不需要重新部署 API。 |
| [阶段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) | 有关适用的属性和支持的操作，请参阅 [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html)。此更新不需要重新部署 API。 |
| [用法](https://docs.aws.amazon.com/apigateway/latest/api/API_GetUsage.html) | 有关适用的属性和支持的操作，请参阅 [usage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsage.html)。此更新不需要重新部署 API。 |
| [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) | 有关适用的属性和支持的操作，请参阅 [usageplan:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html)。此更新不需要重新部署 API。 |
# 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 终端节点进行运行状况检查，以管理故障转移。定期测试您的故障转移机制，确保它们按预期运行，并且操作员熟悉您的故障转移过程。