API Gateway 中针对 REST API 的缓存设置
您可以在 API Gateway 中启用 API 缓存来缓存端点的响应。借助缓存,您可以减少向端点发起的调用数量,同时减少向 API 发出的请求的延迟。
为某个阶段启用缓存时,API Gateway 会在指定的生存时间 (TTL) 期间(以秒为单位)缓存来自端点的响应。然后,在响应请求时,API Gateway 会从缓存中查找端点响应,而不会向端点发出请求。API 缓存的默认 TTL 值为 300 秒。最大 TTL 值为 3600 秒。TTL = 0 表示缓存功能处于禁用状态。
缓存是尽力而为。您可以使用 Amazon CloudWatch 中的 CacheHitCount 和 CacheMissCount 指标,以监控 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 大约需要 4 分钟来完成对缓存的创建或删除。
创建缓存后,缓存集群值会从 Create in progress 变为 Active。完成缓存删除后,缓存集群值会从 Delete in progress 变为 Inactive。
当您为阶段上的所有方法开启方法级缓存时,默认方法级缓存值将变为 Active。如果您为阶段上的所有方法关闭方法级缓存,默认方法级缓存值将变为 Inactive。如果您有方法级缓存的现有设置,则更改缓存的状态不会影响该设置。
当您在阶段的缓存设置中启用缓存时,仅对 GET 方法进行缓存。要确保您的 API 的安全性和可用性,我们建议您不要更改此设置。不过,您可以通过 覆盖方法设置 为其他方法启用缓存。
如果想要验证缓存是否按预期正常运行,您有两种常规选择:
-
针对您的 API 和阶段,检查 CacheHitCount 和 CacheMissCount 的 CloudWatch 指标。
-
在响应中放置一个时间戳。
请不要使用来自 CloudFront 响应的 X-Cache 标头,来确定您的 API 是否由 API Gateway 缓存实例提供服务。
覆盖方法级缓存的 API Gateway 阶段级缓存
您可以通过为特定方法开启或关闭缓存来覆盖阶段级缓存设置。您还可以修改 TTL 期间,或者为缓存的响应开启或关闭加密。
如果您预计正缓存的方法会在其响应中接收敏感数据,请加密缓存数据。为遵守各种合规性框架,您可能需要执行此操作。有关更多信息,请参阅《Amazon Security Hub User Guide》中的 Amazon API Gateway Controls。
将方法或集成参数用作索引缓存响应的缓存键
可以将方法或集成参数用作缓存键来对缓存的响应编制索引。这包括自定义标头、URL 路径或查询字符串。可以将这些参数中的一部分或全部指定为缓存键,但必须至少指定一个值。当您有缓存键时,API Gateway 会分别缓存来自每个键值的响应,包括缓存键不存在的情况。
在资源上设置缓存时需要缓存键。
例如,假设您在以下格式中提出一个请求:
GET /users?type=... HTTP/1.1 host: example.com ...
在这个请求中,type 的值可以是 admin 或 regular。如果您添加 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 阶段缓存
启用 API 缓存时,您可以刷新 API 阶段的整个缓存,以确保您的 API 客户端可以从集成端点获得最新响应。
刷新缓存之后,在重新构建缓存之前,从集成端点为响应提供服务。在此期间,发送到集成端点的请求数量可能会增加。这可能会临时增加 API 的整体延迟。
使 API Gateway 缓存条目失效
您的 API 客户端可以使某个现有缓存条目失效,也可以从各个请求的集成端点重新加载该条目。客户端必须发送一个包含 Cache-Control: max-age=0 标头的请求。客户端将直接从集成端点 (而非缓存) 收到响应,前提是客户端获得授权执行此操作。这会将现有缓存条目替换为从集成端点获得的新响应。
要为客户端授予权限,请将以下格式的策略附加到用户的 IAM 执行角色。
不支持跨账户缓存无效化。
此策略允许 API Gateway 执行服务让指定资源上的请求对应的缓存失效。要指定一组目标资源,请将 account-id 的 ARN 值中的 api-id、Resource 和其他条目替换为通配符 (*)。有关如何为 API Gateway 执行服务设置权限的更多信息,请参阅使用 IAM 权限控制对 REST API 的访问。
如果您未应用 InvalidateCache 策略(或在控制台中选中需要授权复选框),则任何客户端均可使 API 缓存失效。如果大部分或全部客户端都使 API 缓存失效,这会显著增加 API 的延迟。
策略到位后,将启用缓存并需要授权。
您可以在以下选项中选择 API Gateway 如何处理未经授权的请求:
- 使请求失败,返回 403 状态代码
API Gateway 返回
403 Unauthorized响应。要使用 API 设置该选项,请使用
FAIL_WITH_403。- 忽略缓存控制标头;在响应标头中添加警告
API Gateway 处理请求并在响应中添加警告标头。
要使用 API 设置该选项,请使用
SUCCEED_WITH_RESPONSE_HEADER。- 忽略缓存控制标头
API Gateway 处理请求,但不在响应中添加警告标头。
要使用 API 设置该选项,请使用
SUCCEED_WITHOUT_RESPONSE_HEADER。
您可以使用 API Gateway 控制台或 Amazon CLI,针对未经授权的请求来设置处理行为。
Amazon CloudFormation带有缓存的阶段的 示例
以下 Amazon CloudFormation 模板创建示例 API,为 Prod 阶段预置 0.5 GB 的缓存,并为所有 GET 方法启用方法级别的缓存。
缓存功能基于您选择的缓存大小按小时计费。缓存没有资格享受 Amazon 免费套餐。有关更多信息,请参阅 API Gateway 定价
AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: cache-example PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api ApiStage: Type: 'AWS::ApiGateway::Stage' Properties: StageName: Prod Description: Prod Stage with a cache RestApiId: !Ref Api DeploymentId: !Ref ApiDeployment CacheClusterEnabled: True CacheClusterSize: 0.5 MethodSettings: - ResourcePath: /* HttpMethod: '*' CachingEnabled: True