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

启用 API 缓存以增强响应能力

您可以在 Amazon API Gateway 中启用 API 缓存以缓存终端节点的响应。借助缓存,您可以减少向终端节点发起的调用数量,同时减少向 API 发出的请求的延迟。为某个阶段启用缓存时,API Gateway 会在指定的生存时间 (TTL) 期间 (以秒为单位) 缓存来自终端节点的响应。然后,在响应请求时,API Gateway 会从缓存中查找终端节点响应,而不会向终端节点发出请求。API 缓存的默认 TTL 值为 300 秒。最大 TTL 值为 3600 秒。TTL = 0 表示缓存功能处于禁用状态。

注意

缓存功能按小时计费,不在 AWS 免费套餐范围内。

启用 Amazon API Gateway 缓存

在 API Gateway 中,您可以为某个指定阶段启用所有方法的缓存。启用缓存时,您必须选择一个缓存容量。一般而言,容量越大,性能越高,但成本也更高。

API Gateway 通过创建专用的缓存实例来实现缓存功能。这一过程耗时最多 4 分钟。

API Gateway 通过删除现有缓存实例并重新创建一个具有修改后的容量的新实例来更改缓存容量。所有现有的缓存数据均将被删除。

在 API Gateway 控制台中,您可以在某个已命名的 Stage EditorSettings 选项卡中配置缓存。

要为指定阶段配置 API 缓存,请执行以下操作:

  1. 转到 API Gateway 控制台。

  2. 导航到您想要为其启用缓存的阶段对应的 Stage Editor

  3. 选择 Settings

  4. 选择 Enable API cache

  5. 等待缓存创建完成。

注意

API Gateway 大约需要 4 分钟来完成对缓存的创建或删除。缓存创建完成后,Cache status 值会从 CREATE_IN_PROGRESS 变为 AVAILABLE。缓存删除完成后,Cache status 值会从 DELETE_IN_PROGRESS 变为一个空字符串。

当您在某个阶段的 Cache Settings 中启用缓存时,您就为该阶段中的所有方法启用了缓存。

如果想要验证缓存是否按预期正常运行,您有两种常规选择:

  • 针对您的 API 和阶段,检查 CacheHitCountCacheMissCount 这两项 CloudWatch 指标。

  • 在响应中放置一个时间戳。

注意

您不应使用来自 CloudFront 响应的 X-Cache 标头来确定您的 API 是否受 API Gateway 缓存实例支持。

覆盖方法缓存的 API Gateway 阶段级缓存

如果您想在缓存设置中进行更精细的调整,您可以覆盖各个方法的阶段级缓存。这包括禁用特定方法的缓存、延长或缩短其 TTL 期,以及启用或关闭缓存响应的加密功能。如果您预计某个方法将在其响应中接收敏感数据,请在 Cache Settings 中选择 Encrypt cache data

要使用控制台为各个方法配置 API 缓存,请执行以下操作:

  1. 从主导航窗格中选择 API 的 Stages

  2. 从二级导航窗格,在所选阶段中选择 API 的一个方法。

  3. Settings 中选择 Override for this method

  4. Cache Settings 部分下方选择相应的设置 (仅在启用了阶段级别的缓存时才显示此部分)。

将方法或集成参数用作索引缓存响应的缓存键

当缓存的方法或集成具有参数 (可以是自定义标头、URL 路径或查询字符串格式) 时,您可以使用部分或全部参数来构建缓存键。API Gateway 可以缓存方法的响应,具体取决于使用的参数值。

例如,假设您提出一个以下格式的请求:

GET /users?type=... HTTP/1.1 host: example.com ...

在这个请求中,type 的值可以是 adminregular。如果您添加 type 参数作为缓存键的组成部分,则 GET /users?type=admin 的响应将与 GET /users?type=regular 的响应分开缓存。

当某种方法或集成请求采用多个参数时,您可以选择添加部分或全部参数来创建缓存键。例如,对于在 TTL 期内按列出的顺序提出的以下请求,您可以在缓存键中只添加 type 参数:

GET /users?type=admin&department=A HTTP/1.1 host: example.com ...

该请求的响应会被缓存,并用于响应以下请求:

GET /users?type=admin&department=B HTTP/1.1 host: example.com ...

要在 API Gateway 控制台中将一个方法或集成请求参数添加为缓存键的一部分,请在添加参数后选择 Caching

 将方法或集成参数添加为索引缓存响应的缓存键

在 API Gateway 中刷新 API 阶段缓存

启用 API 缓存时,您可以刷新 API 阶段的整个缓存,以确保您的 API 客户端可以从集成终端节点获得最新响应。

要刷新 API 阶段缓存,可以在 API Gateway 控制台某个阶段编辑器中的设置选项卡中,选择缓存设置部分下的刷新整个缓存按钮。缓存刷新操作几乎可以在瞬间完成。刷新之后,缓存状态将立即变成 AVAILABLE

请注意,刷新缓存后,后续请求均由后端提供响应,直至缓存重新构建完成。在此期间,发送到集成终端节点的请求数量可能会增加。这可能会增大 API 的总体延迟。

使 API Gateway 缓存条目失效

您的 API 客户端可以使某个现有缓存条目失效,也可以从各个请求的集成终端节点重新加载该条目。客户端必须发送一个包含 Cache-Control: max-age=0 标头的请求。客户端将直接从集成终端节点 (而非缓存) 收到响应,前提是用户获得授权执行此操作。这会将现有缓存条目替换为从集成终端节点获得的新响应。

要为调用方授予权限,请将以下格式的策略附加到用户的 IAM 执行角色。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:InvalidateCache" ], "Resource": [ "arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier" ] } ] }

此策略允许 API Gateway 执行服务让指定资源上的请求对应的缓存失效。要指定一组目标资源,请将 Resource 的 ARN 值中的 account-idapi-id 和其他条目替换为通配符 (*)。有关如何为 API Gateway 执行服务设置权限的更多信息,请参阅使用 IAM 许可控制对 API 的访问

如果您未应用 InvalidateCache 策略,则任何客户端都可以使 API 缓存失效。如果全部或大部分客户端都使 API 缓存失效,您的 API 延迟可能会严重增大。

当应用了策略、启用了缓存并设定了权限限制时,您可以从 API Gateway 控制台中的 Handle unauthorized requests 选择相应选项,控制对未经授权的请求的处理方式。

 配置缓存失效

这三个选项会引发以下行为:

  • Fail the request with 403 status code:返回“403 Unauthorized”响应。

    要使用 API 设置该选项,请使用 FAIL_WITH_403

  • Ignore cache control header; Add a warning in response header:处理请求并在响应中添加一条警告标头。

    要使用 API 设置该选项,请使用 SUCCEED_WITH_RESPONSE_HEADER

  • Ignore cache control header:处理请求,但不在响应中添加警告标头。

    要使用 API 设置该选项,请使用 SUCCEED_WITHOUT_RESPONSE_HEADER