ResponseCache 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

缓存来自后端资源的数据，从而减少对资源的请求数量。当应用向同一 URI 发出请求时，可以使用此政策返回缓存的响应，而不是将这些请求转发到后端服务器。ResponseCache 政策可通过降低延迟和减少网络流量来提高 API 的性能。

如果您的 API 使用的后端数据仅会定期更新时，您就很可能会发现 ResponseCache 最为有用。例如，假设您用于公布天气报告数据的 API 仅会每 10 分钟刷新一次时。通过使用 ResponseCache 在刷新之间返回缓存的响应，您可以减少到达后端的请求数量。这也减少了网络跃点的数量。

对于通用短期缓存，请考虑使用填充缓存政策。该政策与查找缓存政策（用于读取条目）和让缓存失效政策（用于使条目失效）结合使用。

请观看此视频，了解响应缓存政策。

示例

10 分钟缓存

以下示例演示了如何将缓存的响应保留 10 分钟。

假设您有一个位于以下网址的 API：

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

您需要使用查询参数 w 作为缓存键。每当收到请求时，Apigee Edge 都会检查查询参数 w 的值。如果缓存中存在有效（即未过期）的响应，则会将缓存的响应消息将返回到请求客户端。

现在假设您按如下方式配置了 ResponseCache 政策。

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

当 API 代理首次收到以下网址的请求消息时，将会缓存响应。在 10 分钟内收到第二个请求时，会发生缓存查找 - 系统会将缓存的响应会返回给应用，并且不会将请求转发给后端服务。

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

跳过缓存查找

以下示例展示了如何跳过缓存查找并刷新缓存。另请观看此视频，了解如何使用 SkipCacheLookup。

可选的 SkipCacheLookup 条件（如果已配置）在请求路径中进行计算。如果条件计算结果为 true，则系统会跳过缓存查找并刷新缓存。

条件缓存刷新的常见用法是定义导致条件计算结果为 true 的特定 HTTP 标头。通过脚本编写的客户端应用可配置为定期提交具有适当 HTTP 标头的请求，从而明确触发刷新响应缓存。

例如，假设调用以下网址的一个 API：

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

现在假设在该代理上配置了以下 ResponseCache 政策。请注意，Bypass-cache 条件设置为 true。

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

如需详细了解条件，请参阅流变量和条件。

元素参考

元素参考介绍了政策的元素和属性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

<ResponseCache> 属性

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

下表介绍了所有政策父元素通用的特性：

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 true 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 name 属性的值。
状态 可选
类型 字符串

<CacheKey> 元素

配置存储在缓存中的数据块的唯一指针。

缓存键的大小限制为 2 KB。

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

默认：

不适用

状态：

 必需

类型：

不适用

<CacheKey> 构造缓存中存储的每个数据块的名称。键通常使用实体标头或查询参数中的值进行设置。在这些情况下，您可以让元素的 ref 属性指定一个包含键值的变量。

在运行时，<KeyFragment> 值前面会附加 <Scope> 元素值或 <Prefix> 值。例如，以下命令会产生 UserToken__apiAccessToken__<value_of_client_id> 的缓存键：

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

您可将 <CacheKey> 元素与 <Prefix> 和 <Scope> 搭配使用。如需了解详情，请参阅使用缓存键。

<CacheLookupTimeoutInSeconds> 元素

指定缓存查找失败后的秒数，经过此时间之后将视为缓存未命中。如果发生这种情况，流会沿着缓存未命中的路径继续执行。

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

默认：

30

显示：

 选填

类型：

整数

<CacheResource> 元素

指定存储消息的缓存。 省略此元素可使用所包括的共享缓存。如果您希望能够管理性清理缓存中包含的条目，则应该按名称指定 CacheResource。如需了解详情，请参阅缓存。

<CacheResource>cache_to_use</CacheResource>

默认：

不适用

状态：

 选填

类型：

字符串

如需详细了解如何配置缓存，请参阅创建和修改环境缓存。

<CacheKey>/<KeyFragment> 元素

指定应在缓存键中包含的值，从而创建用于将请求与缓存响应匹配的命名空间。

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

默认：

不适用

状态：

 选填

类型：

不适用

这可以是键（您提供的静态名称）或值（通过引用变量设置的动态条目）。组合的所有指定片段（加上前缀）都串联在一起以创建缓存键。

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

您可将 <KeyFragment> 元素与 <Prefix> 和 <Scope> 搭配使用。如需了解详情，请参阅使用缓存键。

属性

属性 类型 默认 必需 说明
ref string 否

要从中获取值的变量。如果此元素包含字面量值，则不应使用此属性。

<CacheKey>/<Prefix> 元素

指定要用作缓存键前缀的值。

<Prefix>prefix_string</Prefix>

默认：

不适用

状态：

 选填

类型：

字符串

如果您想指定自己的值，而不是 <Scope> 枚举值，请使用此值，而不是 <Scope>。如果已定义，<Prefix> 将在写入缓存的条目的缓存键值前面。<Prefix> 元素值会替换 <Scope> 元素值。

您可将 <Prefix> 元素与 <CacheKey> 和 <Scope> 搭配使用。如需了解详情，请参阅使用缓存键。

<ExcludeErrorResponse> 元素

目前，默认情况下，此政策会缓存 HTTP 响应以及任何可能状态代码。这意味着成功响应和错误响应都会缓存。例如，默认情况下，会缓存具有 2xx 和 3xx 状态码的响应。

如果您不想缓存具有 HTTP 错误状态代码的目标响应，请将此元素设为 true；如果此元素为 true，则只缓存具有从 200 到 205 的状态代码的响应。这些是 Edge 仅将其计为“成功”代码的 HTTP 状态代码，您无法更改此关联。

如需查看关于此元素发挥作用的响应缓存模式的讨论，请参阅此社区帖子。

注意：在将来的版本中（待定），此元素的默认设置将更改为 true。如需了解详情，请参阅 Apigee 版本说明。

<ExcludeErrorResponse>true</ExcludeErrorResponse>

默认：

false

状态：

 选填

类型：

布尔值

<ExpirySettings> 元素

指定缓存条目何时失效。如果存在，<TimeoutInSeconds> 将同时替换 <TimeOfDay> 和 <ExpiryDate>。

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

默认：

不适用

状态：

 必需

类型：

不适用

<ExpirySettings>/<ExpiryDate> 元素

指定缓存条目应失效的日期。使用格式 mm-dd-yyyy。 如果存在，该元素的同级 <TimeoutInSeconds> 将替换 <ExpiryDate>。

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

默认：

不适用

状态：

 选填

类型：

字符串

属性

<ExpiryDate ref="" />
特性 说明 默认 状态 类型
ref

要从中获取值的变量。如果此元素包含字面量值，则不应使用此属性。

 不适用 选填 字符串

<ExpirySettings>/<TimeOfDay> 元素

缓存条目应失效的时间。使用格式 hh:mm:ss。如果存在，该元素的同级 <TimeoutInSeconds> 将替换 <TimeOfDay>。

以 HH:mm:ss 格式输入时间，其中 HH 表示 24 小时制的小时。例如，14:30:00 表示下午 2:30。

对于时间，默认语言区域和时区将因代码运行位置而异（在配置政策时尚不知）。 如需了解如何配置语言区域，请参阅创建和修改环境缓存。

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

默认：

 不适用

状态：

 选填

类型：

字符串

属性

特性 说明 默认 状态 类型
ref 具有失效时间值的变量。 不适用 选填 字符串

<ExpirySettings>/<TimeoutInSec> 元素

之后缓存条目应失效的秒数。

<ExpirySettings>/<TimeoutInSeconds> 元素

之后缓存条目应失效的秒数。如果存在，此元素将替换其同级 <TimeOfDay> 和 <ExpiryDate>。

<ExpirySettings>
    <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
</ExpirySettings>

注意：如果 ref 未从 duration_variable 收到值，请提供一个默认超时值。

默认：

不适用

状态：

 选填

类型：

字符串

属性

特性 说明 默认 状态 类型
ref 包含超时值的变量。
不适用
选填 字符串

<Scope> 元素

在 <CacheKey> 元素中未提供 <Prefix> 元素时，用于构造缓存键前缀的枚举。

<Scope>scope_enumeration</Scope>

默认：

“专有”

状态：

 选填

类型：

字符串

<Scope> 设置确定根据 <Scope> 值前置的缓存键。例如，当范围设置为 Exclusive 时，缓存键将采用以下格式：orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]。

如果 <CacheKey> 中存在 <Prefix> 元素，则它会取代 <Scope> 元素值。有效值包括以下枚举。

您可将 <Scope> 元素与 <CacheKey> 和 <Prefix> 搭配使用。如需了解详情，请参阅使用缓存键。

可接受的值

范围值 说明
Global

缓存密钥可在环境中部署的所有 API 代理之间共享。缓存键的前置格式为 orgName __ envName __。

如果您使用 <KeyFragment> apiAccessToken 和 <Global> 范围定义 <CacheKey> 条目，每个条目都将存储为 orgName__envName__apiAccessToken，后跟访问令牌的序列化值。对于部署在名为“apifactory”的组织中名为“test”的环境中的 API 代理，访问令牌将存储在以下缓存键下：apifactory__test__apiAccessToken。
Application

API 代理名称用作前缀。

缓存键的前置格式为 orgName__envName__apiProxyName。
Proxy

ProxyEndpoint 配置用作前缀。

缓存键的前置格式为 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName。
Target

TargetEndpoint 配置用作前缀。

前缀键的前置格式为 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName。
Exclusive

默认值。这是最具体的，因此在给定缓存中，可将命名空间冲突降至最低。

前缀采用以下两种格式之一：

  • 如果将政策附加到 ProxyEndpoint 流，则前缀格式为 ApiProxyName_ProxyEndpointName。
  • 如果将政策附加在 TargetEndpoint，则前缀格式为 ApiProxyName_TargetName。

缓存键的前置格式为 orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

例如，完整的字符串可能如下所示：

apifactory__test__weatherapi__16__default__apiAccessToken
。

<SkipCacheLookup> 元素

定义表达式，如果它在运行时计算为 true，则指定应跳过缓存查询，并且应刷新缓存。另请观看此视频，了解如何使用 SkipCacheLookup。

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

默认：

不适用

状态：

 选填

类型：

字符串

在以下示例中，如果 bypassa-cache 变量设置为 true，则会跳过缓存查找并刷新缓存。

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

<SkipCachePopulation> 元素

定义表达式，如果它在运行时计算为 true，则指定应跳过写入缓存。另请观看此视频，了解如何使用 SkipCachePopulation。

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

默认：

不适用

状态：

 选填

类型：

字符串

例如，如果响应状态代码为 400 或更高，则以下代码将跳过写入缓存：

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

<UseAcceptHeader> 元素

设置为 true 可将响应缓存条目的缓存键附加到响应 Accept 标头中的值。

Edge 在计算缓存键时会使用 Accept、Accept-Encoding、Accept-Language 和 Accept-Charset 请求标头。这种方法可以防止客户端收到他们未曾要求的媒体类型。

例如，假设两个请求来自同一网址，第一个请求接受 gzip，第二个请求不接受。第一个请求将缓存，缓存的条目（可能）是经过 gzip 处理的响应。第二个请求将读取缓存的值，随后可能会向无法读取 gzip 的客户端返回经过 gzip 处理的条目。

如需了解详情，请参阅配置缓存键。

<UseAcceptHeader>false</UseAcceptHeader>

默认：

false

状态：

 选填

类型：

布尔值

<UseResponseCacheHeaders> 元素

设置为 true 以在缓存中设置响应的“存留时间”(TTL) 时考虑 HTTP 响应标头。如果为 true，Edge 会在设置存留时间时考虑以下响应标头的值，并将这些值与 <ExpirySettings> 设置的值进行比较：

  • Cache-Control s-maxage
  • Cache-Control max-age
  • Expires

如需了解详情，请参阅设置缓存条目到期时间。

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

默认：

false

状态：

 选填

类型：

布尔值

使用说明

每个缓存对象的大小上限为 256 KB。（如需详细了解 Edge 如何处理缓存，请参阅缓存内部构件。）

通过 ResponseCache 政策中的配置，您可以在设置缓存条目到期时间和缓存键时让 Edge 包含 HTTP 响应标头。本部分介绍如何使用具有标头的政策来管理缓存到期时间和缓存键。

如需详细了解 Edge 如何使用 ResponseCache 政策处理响应标头，请参阅 HTTP 响应标头支持。

设置缓存条目到期时间

与填充缓存政策一样，您可以使用 <ExpirySettings> 元素设置响应缓存条目的到期时间（其存留时间）。在 ResponseCache 政策中，您还可以让 Edge 考虑响应标头（如果存在）。

如需使用响应标头，请将 <UseResponseCacheHeaders> 元素值设置为 true。此设置会使 Edge 考虑响应标头，将它们与 <ExpirySettings> 设置的值进行比较，然后使用两者之间的最小值。在考虑响应标头时，Edge 会选择可用值，如下所述：

例如，假设缓存了响应及以下值：

  • 没有 Cache-Control s-maxage 值
  • Cache-Control max-age 值为 300
  • Expires 日期为三天
  • <ExpirySettings> TimeoutInSeconds 值为 600。

在这种情况下，会将 Cache-Control max-age 值用于存留时间 (TTL)，因为它低于 <ExpirySettings> 值并且因为没有Cache-Control s-maxage 值（该值优先于 max-age）。

配置缓存键

与填充缓存政策等通用缓存政策一样，您可以通过 ResponseCache 使用 <CacheKey> 和 <Scope> 元素为缓存条目配置缓存键创建。您还可以通过 ResponseCache 让缓存键更有意义，方法是将响应 Accept 标头附加到键值。

如需了解配置缓存键的一般信息，请参阅使用缓存键。如需了解如何使用 Accept 标头，请参阅 <UseAcceptHeader>。

缓存加密简介

针对公有云的 Edge：缓存仅在启用了 PCI 和 HIPAA 的组织中进行加密。这些组织的加密会在组织预配期间进行配置。

流变量

执行 ResponseCache 政策时，将会填充以下预定义的流变量。如需详细了解流变量，请参阅变量参考。

变量 类型 权限 说明
responsecache.{policy_name}.cachename 字符串 只读 返回在政策中使用的缓存
responsecache.{policy_name}.cachekey 字符串 只读 返回所使用的密钥
responsecache.{policy_name}.cachehit 布尔值 只读 如果政策执行成功，则为 true
responsecache.{policy_name}.invalidentry 布尔值 只读 如果缓存条目无效，则为 true

错误代码

本部分介绍当此政策触发错误时所设置的错误消息和流变量。在为代理开发故障规则时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

错误代码前缀

不适用

运行时错误

此政策不会抛出任何运行时错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因 修复
InvalidTimeout 如果 ResponseCache 政策的 <CacheLookupTimeoutInSeconds> 元素设置为负数，则 API 代理的部署将会失败。
InvalidCacheResourceReference 如果将 ResponseCache 政策中的 <CacheResource> 元素设置为部署 API 代理的环境中不存在的名称，则会出现此错误。
ResponseCacheStepAttachmentNotAllowedReq 如果将同一 ResponseCache 政策附加到 API 代理的任何流中的多个请求路径，则会出现此错误。
ResponseCacheStepAttachmentNotAllowedResp 如果将同一 ResponseCache 政策附加到 API 代理的任何流中的多个响应路径，则会出现此错误。
InvalidMessagePatternForErrorCode 如果 ResponseCache 政策中的 <SkipCacheLookup> 或 <SkipCachePopulation> 元素包含无效条件，则会出现此错误。
CacheNotFound 如果尚未在特定的消息处理器组件上创建错误消息中提及的特定缓存，就会发生此错误。

故障变量

无

错误响应示例

不适用

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。