ResponseCache 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

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

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

请观看下面的视频，了解响应缓存政策。

示例

10 分钟缓存

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

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

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

您需要使用查询参数 w 作为缓存键。每当收到请求时，Apigee 都会检查查询参数 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

提示：在收到请求时，HTTP 标头和查询参数会作为变量自动填充。任何 HTTP 标头均作为 request.header.{header_name} 提供，例如 request.header.user-agent。任何查询参数均作为 request.queryparam.{queryparam_name} 提供，例如 request.queryparam.action。

跳过缓存查找

以下示例展示了如何跳过缓存查找并刷新缓存。另请观看此视频，了解如何使用 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`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障	false	可选
`enabled`	设置为 `true` 可强制执行政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	是	可选
`async`	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

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

不适用

如果省略此元素，则会使用政策的 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。如需了解详情，请参阅 Caches API。

<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	字符串		否	要从中获取值的变量。如果此元素包含字面量值，则不应使用此属性。

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

默认：	不适用
状态：	可选
类型：	字符串

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

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

<ExcludeErrorResponse> 元素

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

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

如需查看关于此元素发挥作用的响应缓存模式的讨论，请参阅反模式简介。

<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> 元素

注意：被弃用。使用 TimeoutInSeconds。如果 TimeoutInSec 和 TimeoutInSeconds 元素同时存在，Apigee 使用 TimeoutInSeconds。

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

<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，则指定应跳过缓存查询，并且应刷新缓存。另请观看使用 ResponseCache 政策视频，了解如何使用 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 标头中的值。

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

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

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

<UseAcceptHeader>false</UseAcceptHeader>

默认：	false
状态：	可选
类型：	布尔值

<UseResponseCacheHeaders> 元素

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

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

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

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

默认：	false
状态：	可选
类型：	布尔值

使用说明

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

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

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

设置缓存条目到期时间

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

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

显示将 UseResponseCacheHeaders 设置为 true 时将发生的情况的图表。

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

没有 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）。

配置缓存键

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

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

缓存加密简介

Apigee 和 Apigee Hybrid（1.4 版及更高版本）：缓存数据和 KVM 数据始终处于加密状态。

流变量

执行 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 提供了政策架构作为参考。