启用 API 缓存以增强响应能力 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

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

您可以在 Amazon API Gateway 中启用 API 缓存以缓存您的终端节点的响应。借助缓存,您可以减少向终端节点发起的调用数量,同时减少向 API 发出的请求的延迟。

当您为某个阶段启用缓存时,API Gateway 会将来自终端节点的响应缓存指定的 time-to-live (TTL) 时间(以秒为单位)。然后,在响应请求时,API Gateway 会从缓存中查找终端节点响应,而不会向终端节点发出请求。API 缓存的默认 TTL 值为 300 秒。最大 TTL 值为 3600 秒。TTL = 0 表示缓存功能处于禁用状态。

注意

缓存是尽力而为。您可以使用亚马逊中的CacheHitCountCacheMissCount指标 CloudWatch 来监控 API Gateway 从 API 缓存中提供的请求。

可缓存的响应的最大大小为 1048576 字节。缓存数据加密可能会增加缓存时的响应的大小。

这是一项符合 HIPAA 要求的服务。有关 Amazon《1996 年美国健康保险流通与责任法案》(HIPAA) 以及使用 Amazon 服务处理、存储和传输受保护的健康信息 (PHI) 的更多信息,请参阅 HIPAA 概述。

重要

为某个阶段启用缓存时,默认情况下,仅 GET 方法已启用缓存。这有助于确保您的 API 的安全性和可用性。您可以通过覆盖方法设置为其他方法启用缓存。

重要

缓存功能基于您选择的缓存大小按小时计费。缓存不符合 Amazon 免费套餐的资格。有关更多信息,请参阅 API Gateway 定价

启用 Amazon API Gateway 缓存

在 API Gateway 中,您可以为特定阶段启用缓存。

启用缓存时,您必须选择一个缓存容量。一般而言,容量越大,性能越高,但成本也更高。有关支持的缓存大小,请参阅《API Gateway API 参考cacheClusterSize中的。

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

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

注意

缓存容量会影响缓存实例的 CPU、内存和网络带宽。因此,缓存容量会影响缓存的性能。

API Gateway 建议您运行 10 分钟的负载测试,来验证缓存容量是否适用于您的工作负载。确保负载测试期间的流量能够反映生产流量。例如,包括流量增加、流量恒定和流量高峰。负载测试应包括缓存可提供的响应以及向缓存添加项的唯一响应。监控负载测试期间的延迟、4xx、5xx、缓存命中和缓存未命中指标。根据这些指标,按需调整缓存容量。有关负载测试的更多信息,请参阅如何选择最佳 API Gateway 缓存容量以避免达到速率限制?

在 API Gateway 控制台中,您可以在阶段页面上配置缓存。您可以配置阶段缓存并指定默认的方法级缓存设置。如果您打开默认的方法级缓存,则会为舞台上的所有方法启用方法级缓存,除非该方法有方法覆盖。部署到舞台的任何其他GET方法都将具有方法级缓存。要为舞台的特定方法配置方法级缓存设置,可以使用方法重写。有关方法重写的更多信息,请参见覆盖 API Gateway 阶段级缓存以实现方法级缓存

要为指定阶段配置 API 缓存,请执行以下操作:
  1. 通过以下网址登录到 API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择 Stages (阶段)

  3. 在 API 的Stages (阶段) 列表中,选择阶段。

  4. 阶段详细信息部分中,选择编辑

  5. 其他设置下,对于缓存设置,打开配置 API 缓存

    这将为您的阶段预置一个缓存集群。

  6. 要激活舞台的缓存,请开启默认方法级缓存。

    这将为舞台上的所有方法开启方法级缓存。您部署到此阶段的任何其他GET方法都将具有方法级缓存。

    注意

    如果您有方法级缓存的现有设置,则更改默认的方法级缓存设置不会影响该现有设置。

  7. 选择 ‬保存更改

注意

API Gateway 大约需要 4 分钟来完成对缓存的创建或删除。

创建缓存后,缓存集群Create in progress将从变为Active。缓存删除完成后,缓存集群Delete in progress将从变为Inactive

当您在舞台上为所有方法启用方法级缓存时,默认方法级缓存值将更改为。Active如果您关闭舞台上所有方法的方法级缓存,则默认方法级缓存值将更改为。Inactive如果您有方法级缓存的现有设置,则更改缓存状态不会影响该设置。

当您在阶段的缓存设置中启用缓存时,仅对 GET 方法进行缓存。要确保您的 API 的安全性和可用性,我们建议您不要更改此设置。不过,您可以通过 覆盖方法设置 为其他方法启用缓存。

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

  • 检查您的 API CacheHitCountCacheMissCount和阶段的 CloudWatch 指标。

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

注意

您不应使用 CloudFront 响应中的X-Cache标头来确定您的 API 是否由您的 API Gateway 缓存实例提供。

覆盖 API Gateway 阶段级缓存以实现方法级缓存

您可以通过开启或关闭特定方法的缓存来覆盖阶段级缓存设置。您也可以修改 TTL 周期,或者为缓存的响应开启或关闭加密。

如果您在舞台详细信息中更改默认的方法级缓存设置,则不会影响具有覆盖功能的方法级缓存设置。

如果您预计某个进行缓存的方法将在其响应中接收敏感数据,请在 缓存设置 中选择 加密缓存数据

要使用控制台为各个方法配置 API 缓存,请执行以下操作:
  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择 API。

  3. 选择 Stages (阶段)

  4. 在 API 的 Stages (阶段) 列表中,展开阶段,然后在 API 中选择方法。

  5. 方法覆盖部分,选择编辑

  6. 方法设置部分,打开或关闭启用方法缓存或自定义任何其他所需选项。

    注意

    在您为阶段配置缓存集群之前,缓存才会处于活动状态。

  7. 选择保存

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

当缓存的方法或集成具有参数 (可以是自定义标头、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 控制台中将一个方法或集成请求参数添加为缓存键的一部分,请在添加参数后选择缓存

刷新 API Gateway 中的 API 阶段缓存

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

要刷新 API 阶段缓存,请选择阶段操作菜单,然后选择刷新阶段缓存

注意

刷新缓存之后,在重新构建缓存之前,从集成终端节点为响应提供服务。在此期间,发送到集成终端节点的请求数量可能会增加。这可能会临时增加 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/GET/resource-path-specifier" ] } ] }

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

如果您未应用 InvalidateCache 策略(或在控制台中选中 Require authorization (需要授权) 复选框),则任何客户端均可使 API 缓存失效。如果大部分或全部客户端都使 API 缓存失效,这会显著增加 API 的延迟。

策略到位后,将启用缓存并需要授权。

您可以通过从 API Gateway 控制台的 “未授权请求处理” 中选择一个选项来控制如何处理未经授权的请求。

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

  • 请求失败,显示 403 状态代码:返回“403 Unauthorized”响应。

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

  • 忽略缓存控制标头;在响应中添加一条警告标头:处理请求并在响应中添加一条警告标头。

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

  • 忽略缓存控制标头:处理请求,但不在响应中添加警告标头。

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