Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用 API Gateway 控制台设置阶段

创建新阶段

初始部署后,您可以添加更多阶段,并将它们与现有部署进行关联。在部署 API 时,您可以使用 API Gateway 控制台来创建和使用新阶段或选择现有阶段。一般来说,重新部署 API 之前,您可以向 API 部署中添加新阶段。要使用 API Gateway 控制台执行此操作,请遵循以下说明。

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. APIs 导航窗格中,选择某个 API 下的阶段

  3. 阶段导航窗格中,选择 创建

  4. Create Stage (创建阶段) 下,键入阶段名称,例如,为 Stage name (阶段名称) 键入 prod

    注意

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

  5. (可选)为 Stage description (阶段描述) 键入阶段描述

  6. 部署下拉列表中,选择要与此阶段关联的现有 API 部署的日期和时间。

  7. 选择 Create

更新阶段设置

成功部署 API 后,系统将使用默认设置填充阶段。您可以使用控制台或 API Gateway REST API 更改阶段设置,包括 API 缓存和日志记录。接下来,我们将展示如何使用 API Gateway 控制台的 Stage Editor (阶段编辑器) 来执行这一操作。

使用 API Gateway 控制台更新阶段设置

这些步骤假设您已将 API 部署到阶段。

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. API 窗格中,选择 API,然后选择 Stages (阶段)

  3. Stages (阶段) 窗格中,选择该阶段的名称。

  4. Stage Editor (阶段编辑器) 窗格中,选择设置选项卡。

  5. 要为阶段启用 API 缓存,请在 Cache Settings (缓存设置) 部分下选择 Enable API cache (启用 API 缓存) 选项。然后,为 Cache capacity (缓存容量)Encrypt cache data (加密缓存数据)Cache time-to-live (TTL) (缓存生存时间 (TTL)) 选择所需选项和相关值,并为每个密钥缓存失效选择要求。

    有关阶段级别缓存设置的更多信息,请参阅 启用 API 缓存

    重要

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

    提示

    您还可以覆盖各个方法的阶段级缓存设置。为此,请在阶段二级导航窗格下展开此阶段,然后选择一种方法。接下来,在阶段编辑器中,对于设置选择 Override for this method (覆盖此方法) 选项。在 Cache Settings (缓存设置) 区域中,您可以设置或清除 Enable Method Cache (启用方法缓存) 或自定义任何其他所需选项。有关方法级别缓存设置的更多信息,请参阅 启用 API 缓存

  6. 要为与此 API Gateway API 的此阶段相关联的所有方法启用 Amazon CloudWatch Logs,请执行以下操作:

    1. CloudWatch 设置部分下,选择启用 CloudWatch Logs 选项。

      提示

      要启用方法级别 CloudWatch 设置,请在阶段二级导航窗格下展开此阶段,选择感兴趣的每种方法,然后返回阶段编辑器,对于设置选择 Override for this method (覆盖此方法)。在 CloudWatch 设置区域中,请确保先选择记录到 CloudWatch Logs 和任何其他所需选项,然后再选择 Save Changes (保存更改)

      重要

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

    2. 对于 Log level (日志级别),请选择 ERROR (错误),以便只将错误级条目写入 CloudWatch Logs,或选择 INFO (信息) 以包含所有 ERROR (错误) 事件及额外的信息性事件。

    3. 要记录完整的 API 调用请求和响应信息,请选择 Log full requests/responses data (记录完整的请求/响应数据)。除非已选中 Log full requests/responses data (记录完整的请求/响应数据) 选项,否则系统不会记录任何敏感数据。

      重要

      将日志设置为 ERROR,然后选择 Log full requests/responses data (记录完整的请求/响应数据),将导致详细地记录每个请求。这是预期行为。

    4. 要让 API Gateway 向 CloudWatch 报告 API callsLatencyIntegration latency400 errors500 errors 的 API 指标,请选择 Enable Detailed CloudWatch Metrics (启用详细的 CloudWatch 指标) 选项。有关 CloudWatch 的更多信息,请参阅 Amazon CloudWatch 用户指南

    5. 选择 Save Changes。新设置将在新部署完成后生效。

      重要

      要为全部或部分方法启用 CloudWatch Logs,您还必须为某个 IAM 角色指定 ARN,使 API Gateway 能代表您的 IAM 用户将信息写入 CloudWatch Logs。为此,请从 APIs 主导航窗格中选择设置。然后在 CloudWatch 日志角色 ARN 文本字段中键入某个 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 用户指南

  7. 要为与该 API 相关联的所有方法设置阶段级别限制,请在 Default Method Throttling (默认方法限制) 部分中执行以下操作:

    1. 选择 Enable throttling (启用限制)

    2. 对于 Rate (速率),请键入 API Gateway 在不返回 429 Too Many Requests 响应的情况下可以提供的每秒最大阶段级别稳态请求数。该阶段级别速率限制不得超过 配置和运行 REST API 的 API Gateway 限制 中指定的 账户级别速率限制。

    3. 对于 Burst (突增),请键入 API Gateway 在不返回 429 Too Many Requests 响应的情况下可以提供的最大阶段级别并发请求数。该阶段级别突增限制不得超过 配置和运行 REST API 的 API Gateway 限制 中指定的账户级别突增限制。

  8. 要覆盖单个方法的阶段级别限制,请在阶段二级导航窗格下展开阶段,选择一种方法,然后针对设置选择 Override for this method (覆盖此方法)。在 Method Throttling (方法限制) 部分中,选择相应选项。

  9. 要将 AWS WAF Web ACL 与阶段关联,请从 Web ACL 下拉列表中选择一个 Web ACL。

    注意

    如果需要,请选择 Create Web ACL (创建 Web ACL) 以在新的浏览器选项卡中打开 AWS WAF 控制台,创建 Web ACL,并返回到 API Gateway 控制台将 Web ACL 与阶段关联。

  10. 如果需要,请选择 Block API Request if WebACL cannot be evaluated (Fail- Close) (如果无法评估 WebACL,则阻止 API 请求 (失败 - 关闭))

  11. 要为 API 阶段启用 AWS X-Ray 跟踪:

    1. Stage Editor (阶段编辑器) 窗格中,选择 Logs/Tracing (日志/跟踪) 选项卡。

    2. 要启用 X-Ray 跟踪,请选择 X-Ray 跟踪 下的 启用 X-Ray 跟踪

    3. 要在 X-Ray 控制台中设置采样规则,选择 Set X-Ray Sampling Rules (设置 X-Ray 采样规则)

    4. 如果需要,选择 Set X-Ray Sampling Rules (设置 &xray; 采样规则) 然后转到 X-Ray 控制台配置采样规则

    有关更多信息,请参阅 使用 AWS X-Ray 跟踪 API Gateway API 执行

  12. 选择 Save Changes。新设置将在对阶段重新部署 API 之后生效。

删除 API 的阶段

当您不再需要某个阶段时,可以将其删除,以免为未使用的资源付费。接下来,我们将介绍如何使用 API Gateway 控制台删除阶段 。

警告

删除阶段可能会导致 API 调用方无法使用部分或全部相应的 API。删除阶段无法撤销,但您可以重新创建阶段并将其与相同的部署相关联。

使用 API Gateway 控制台删除阶段

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. 在包含该阶段的 API 名称的框中,选择 Stages (阶段)

  3. Stages (阶段) 窗格中,选择您要删除的阶段,然后选择 Delete Stage (删除阶段)

  4. 系统提示时,选择删除