# 为 API Gateway 中的 REST API 设置阶段
<a name="set-up-stages"></a>

阶段是对某个部署的指定引用，是 API 的快照。您可以使用[阶段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)来管理和优化特定的部署。例如，您可以配置阶段设置，以便启用缓存、自定义请求限制、配置日志记录、定义阶段变量或者附加 Canary 版本进行测试。以下部分介绍如何创建和配置阶段。

## 创建新阶段
<a name="how-to-create-stage-console"></a>

 初始部署后，您可以添加更多阶段，并将它们与现有部署进行关联。在部署 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. 选择**创建阶段**。

## 修改阶段设置
<a name="how-to-stage-settings"></a>

成功部署 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 以使新设置生效。

## 覆盖阶段级别设置
<a name="how-to-method-override"></a>

自定义阶段级别设置后，可以为每个 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. 选择**保存**。