LookupCache 政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

配置如何在运行时检索缓存值。

此政策适用于通用短期缓存。它与 Populate Cache 政策（用于写入条目）和 Invalidate Cache 政策（用于使条目失效）搭配使用。

如需了解如何缓存后端资源的响应，请参阅 Response Cache 政策。

元素参考

下面列出了您可以在此政策中配置的元素。

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <CacheLookupTimeoutInSeconds/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

默认情况下包含共享缓存。如需使用共享缓存，请省略此政策配置中的 <CacheResource> 元素。

如需详细了解底层数据存储区，请参阅缓存内部。如需详细了解如何配置缓存，请参阅创建和修改环境缓存。

<LookupCache> 属性

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

属性 说明 默认 状态
name

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

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

 不适用 必填
continueOnError

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

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

 false 可选
enabled

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

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

 是 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

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

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

不适用

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

<AssignTo> 元素

指定从缓存中检索缓存条目后将为其分配的变量。此变量必须可写入。如果缓存查找未检索值，则不会设置变量。

<AssignTo>variable_to_receive_cached_value</AssignTo>

默认：

不适用

状态：

 必需

类型：

字符串

<CacheKey> 元素

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

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

默认：

不适用

状态：

 必需

类型：

不适用

<CacheKey> 构造缓存中存储的每个数据块的名称。

在运行时，<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> 元素

指定存储消息的缓存。

如果此政策（以及对应的 PopulateCache 和 InvalidateCache 政策）使用了所包含的共享缓存，请完全忽略此元素。

<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> 搭配使用。如需了解详情，请参阅使用缓存键。

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

默认：

“专有”

状态：

 可选

类型：

字符串

<Scope> 设置确定根据 <Scope> 值前置的缓存键。例如，将范围设置为 Exclusive 时，缓存键将采用以下格式：orgName__envName__applicationName__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__applicationName。
Proxy

ProxyEndpoint 配置用作前缀。

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

TargetEndpoint 配置用作前缀。

缓存键的前置格式为 orgName__envName__applicationName__targetEndpointName。
Exclusive

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

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

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

缓存键的前置格式为 orgName__envName__applicationName__proxyNameITargetName

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

apifactory__test__weatherapi__16__default__apiAccessToken
。

使用说明

将此政策用于通用缓存。在运行时，LookupCache 政策会从缓存中检索值，将该值分配给您使用 AssignTo 元素指定的变量（如果未检索任何值，则不会设置该变量）。它会根据通过组合了 CacheKey 和 Scope 元素的配置创建的缓存键查找值。换言之，如需通过 PopulateCache 政策检索添加到缓存的特定值，您的 LookupCache 政策必须配置缓存键元素相关元素，其方式与 PopulateCache 政策相同。

采用 Populate Cache 政策、LookupCache 政策和 InvalidateCache 政策的通用缓存使用您配置的缓存或默认添加的共享缓存。在大多数情况下，底层共享缓存应满足您的需求。如需使用默认缓存，只需省略 <CacheResource> 元素即可。

如需详细了解如何配置缓存，请参阅创建和修改环境缓存。如需详细了解底层数据存储区，请参阅缓存内部。

流变量

流变量可用于配置基于 HTTP 标头或消息内容或者流中可用的上下文的政策和流的动态运行时行为。如需详细了解流变量，请参阅变量参考文档。

自定义您在 LookupCache 政策中定义的缓存行为后，以下预定义的流变量将可用。

变量 类型 权限 说明
lookupcache.{policy-name}.cachename 字符串 只读 返回在政策中使用的缓存名称。
lookupcache.{policy-name}.cachekey 字符串 只读 返回使用的密钥。
lookupcache.{policy-name}.cachehit 布尔值 只读 如果政策为指定的缓存键找到了值，则为 True。
lookupcache.{policy-name}.assignto 字符串 只读 返回为其分配缓存的变量。

错误代码

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

错误代码前缀

不适用

运行时错误

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

部署错误

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

错误名称 原因 修复
InvalidCacheResourceReference 如果将 <CacheResource> 元素设置为部署 API 代理的环境中不存在的名称，就会发生此错误。
InvalidTimeout 如果 <CacheLookupTimeoutInSeconds> 元素设置为负数，则 API 代理的部署将失败。
CacheNotFound 如果尚未在特定的消息处理器组件上创建错误消息中提及的特定缓存，就会发生此错误。

故障变量

无

错误响应示例

不适用