ResponseCache 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 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关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

可选
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

Presence:

可选

类型:

整数

<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 字符串

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

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

默认:

不适用

状态:

可选

类型:

字符串

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

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

<ExcludeErrorResponse> 元素

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

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

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

注意:在将来的版本中(待定),此元素的默认设置将更改为 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> 元素

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