为 API Gateway 中的 REST API 设置阶段 - Amazon API Gateway
创建新阶段更新阶段设置覆盖阶段级别设置

为 API Gateway 中的 REST API 设置阶段

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

创建新阶段

初始部署后，您可以添加更多阶段，并将它们与现有部署进行关联。在部署 API 时，您可以使用 API Gateway 控制台来创建新阶段或选择现有阶段。一般来说，重新部署 API 之前，您可以向 API 部署中添加新阶段。要使用 API Gateway 控制台创建新阶段，请按照下列步骤操作：

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

  2. 选择一个 REST API。

  3. 在主导航窗格中，选择某个 API 下的阶段。

  4. 从阶段导航窗格中，选择创建阶段。

  5. 对于阶段名称，请输入名称，例如 prod。

    注意

    阶段名称只能包含字母数字字符、连字符和下划线。最大长度为 128 个字符。

  6. （可选）。对于描述，请输入阶段描述。

  7. 从部署中，选择要与此阶段关联的现有 API 部署的日期和时间。

  8. 在其它设置下，您可以为阶段指定其它设置。

  9. 选择创建阶段。

修改阶段设置

成功部署 API 后，系统将使用默认设置填充阶段。您可以使用控制台或 API Gateway REST API 更改阶段设置，包括 API 缓存和日志记录。以下步骤说明如何使用 API Gateway 控制台的阶段编辑器来执行这一操作。

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

  2. 选择一个 REST API。

  3. 在主导航窗格中，选择某个 API 下的阶段。

  4. 在阶段窗格中，选择该阶段的名称。

  5. 在阶段详细信息部分中，选择编辑。

  6. （可选）对于阶段描述，输入描述。

  7. 对于其他设置，修改以下设置：

    缓存设置

    要为阶段启用 API 缓存，请开启配置 API 缓存。然后，配置默认方法级缓存、缓存容量、加密缓存数据、缓存生存时间(TTL)，以及每个密钥缓存失效的任何要求。

    在开启默认方法级缓存或为特定方法开启方法级缓存之前，缓存不会处于活动状态。

    有关缓存设置的更多信息，请参阅 API Gateway 中针对 REST API 的缓存设置。

    注意

    如果您为 API 阶段启用 API 缓存，系统可能会针对 API 缓存向您的 AWS 账户收费。缓存没有资格享受 AWS 免费套餐。

    节流设置

    要为与该 API 相关联的所有方法设置阶段级别节流目标，请开启节流。

    针对比率部分，请输入目标率。这是将令牌添加到令牌桶的频率，以每秒请求数计。阶段级别频率不得超过用于配置和运行 REST API 的 API Gateway 配额中规定的账户级别频率。

    针对突增部分，请输入目标突增率。突增频率是令牌桶的容量。这允许在一段时间内通过比目标速率更多的请求。该阶段级别突增率不得超过在 用于配置和运行 REST API 的 API Gateway 配额 中指定的账户级别突增比率。

    注意

    节流费率不是硬限制，应基于最佳效果来应用。在某些情况下，客户端可能会超过您设置的目标。不要依靠使用节流来控制成本或阻止对 API 的访问。考虑使用 AWS Budgets 监控成本和 AWS WAF 来管理 API 请求。

    防火墙和证书设置

    要将 AWS WAF Web ACL 与阶段关联，请从 Web ACL 下拉列表中选择一个 Web ACL。如果需要，请选择如果无法评估 WebACL，则阻止 API 请求(失败 - 关闭)。

    要为您的阶段选择客户端证书，请从客户端证书下拉菜单中选择证书。

  8. 选择继续。

  9. 预览更改，然后选择保存更改。

  10. 要为与此 API Gateway API 的此阶段相关联的所有方法启用 Amazon CloudWatch Logs，请在日志和跟踪部分选择编辑。

    注意

    要启用 CloudWatch Logs，您还必须指定 IAM 角色的 ARN，该角色使 API Gateway 能够代表您的用户将信息写入 CloudWatch Logs。为此，请从 APIs 主导航窗格中选择设置。然后，对于 CloudWatch 日志角色，输入 IAM 角色的 ARN。

    对于常见的应用程序场景，IAM 角色可以附加 AmazonAPIGatewayPushToCloudWatchLogs 的托管策略，其中包括以下访问策略语句：

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

    IAM 角色还必须包含以下信任关系语句：

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

    有关 CloudWatch 的更多信息，请参阅 Amazon CloudWatch 用户指南。

  11. 从 CloudWatch Logs 下拉菜单中选择日志记录级别。日志记录级别如下所示：

    • 关闭 - 不对此阶段开启日志记录。

    • 仅限错误 - 仅对错误启用日志记录。

    • 错误和信息日志 - 对所有事件启用日志记录。

  12. 选择数据跟踪，让 API Gateway 向 CloudWatch 报告阶段的数据跟踪日志记录。这对于排除 API 故障非常有用，但可能会导致记录敏感数据。

    注意

    建议不要为生产 API 启用数据跟踪。

  13. 选择详细指标，让 API Gateway 向 CloudWatch 报告 API calls、Latency、Integration latency、400 errors 和 500 errors 的 API 指标。有关 CloudWatch 的更多信息，请参阅《Amazon CloudWatch 用户指南》中的基本监控和详细监控。

    重要

    我们将针对访问方法级别 CloudWatch 指标而非 API 级或存储级指标向您的账户收费。

  14. 要启用对目标的访问日志记录，请打开自定义访问日志记录。

  15. 对于访问日志目标 ARN，输入日志组或 Firehose 流的 ARN。

    Firehose 的 ARN 格式为 arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}。Firehose 流的名称必须为 amazon-apigateway-{your-stream-name}。

  16. 在日志格式中，输入日志格式。要了解有关示例日志格式的更多信息，请参阅用于 API Gateway 的 CloudWatch 日志格式。

  17. 要为 API 阶段启用 AWS X-Ray 跟踪，请选择 X-Ray 跟踪。有关更多信息，请参阅 在 API Gateway 中使用 X-Ray 跟踪用户对 REST API 的请求。

  18. 选择 Save changes（保存更改）。重新部署 API 以使新设置生效。

覆盖阶段级别设置

自定义阶段级别设置后，可以为每个 API 方法覆盖这些设置。其中一些选项可能会导致您的 AWS 账户产生额外费用。

  1. 要配置方法覆盖，请在二级导航窗格下展开阶段，然后选择一种方法。

    在二级导航窗格下展开阶段，然后选择一种方法。

  2. 对于方法覆盖，选择编辑。

  3. 要开启方法级别 CloudWatch 设置，请为 CloudWatch Logs 选择一个日志记录级别。

  4. 要为您的方法启用数据跟踪日志记录，请选择数据跟踪。

    注意

    建议不要为生产 API 启用数据跟踪。

  5. 要开启方法级别详细指标，请选择详细指标。我们将针对访问方法级别 CloudWatch 指标而非 API 级或存储级指标向您的账户收费。

  6. 要开启方法级别的节流，请选择节流。输入适合的方法级别选项。要了解有关节流的更多信息，请参阅 在 API Gateway 中限制对 REST API 的请求以提高吞吐量。

  7. 要配置方法级别缓存，请选择启用方法缓存。如果您在阶段详细信息中更改默认方法级缓存设置，它不会影响此设置。

  8. 选择保存。