PopulateCache 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

配置如何在运行时写入缓存值。

Populate Cache 政策适用于在短期通用缓存中写入条目。它可与 Lookup Cache 政策(用于读取缓存条目)和 Invalidate Cache 政策(用于使条目失效)搭配使用。

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

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

元素参考

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

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

<PopulateCache> 属性

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails. See also:

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

<CacheKey> 元素

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

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

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

<CacheResource> 元素

指定存储消息的缓存。

如果此政策(以及对应的 LookupCache 和 InvalidateCache 政策)使用了所包含的共享缓存,请完全忽略此元素。

<CacheResource>cache_to_use</CacheResource>

默认:

不适用

状态:

可选

类型:

字符串

如需详细了解如何配置缓存,请参阅通用缓存。

<CacheKey>/<KeyFragment> 元素

指定应在缓存键中包含的值。使用 ref 特性或固定值指定要取消引用的变量。

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

默认:

不适用

状态:

零个或多个

类型:

不适用

在运行时,Apigee 从 <Scope> 元素或 <Prefix> 元素获取值,并将其作为使用各 <KeyFragment> 元素解析值构成的串联的前缀,从而创建缓存键。如需了解详情,请参阅使用缓存键。

属性

属性 类型 默认值 需要 说明
ref 字符串 否

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

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

默认:

不适用

状态:

可选

类型:

字符串

<Prefix> 元素将替换任何 <Scope> 元素。

在运行时,Apigee 从 <Scope> 元素或 <Prefix> 元素获取值,并将其作为使用各 <KeyFragment> 元素解析值构成的串联的前缀,从而创建缓存键。如需了解详情,请参阅使用缓存键。

<ExpirySettings> 元素

指定缓存条目何时失效。

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

默认:

不适用

状态:

需要

类型:

不适用

<ExpirySettings> 的子元素

仅使用一个子元素。下表提供了 <ExpirySettings> 的子元素相关的说明:

子元素 说明
<TimeoutInSeconds>

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

<ExpirySettings>
  <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds>
</ExpirySettings>

此元素取代了现已弃用的 TimeoutInSec 元素。

<ExpiryDate>

指定缓存条目应失效的日期。指定 mm-dd-yyyy 格式的字符串。

<ExpirySettings>
  <ExpiryDate ref="var-containing-date">expiry</ExpiryDate>
</ExpirySettings>

如果指定的日期是过去的日期,则该政策将对缓存条目应用最大存留时间。最大值为 30 天。

<TimeOfDay>

指定缓存条目应失效的时间。 指定 HH:mm:ss 格式的字符串,其中 HH 表示 24 小时制的小时,时区为世界协调时间 (UTC)。例如,14:30:00 表示下午 2:30。

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

您应该仅指定一个可能的子元素。如果您指定多个元素,则优先顺序为:TimeoutInSeconds、ExpiryDate、TimeOfDay。

使用 <ExpirySettings> 的上述每个子元素时,如果您在子元素上指定可选的 ref 属性,政策会从指定的上下文变量中检索到期值。如果未定义该变量,政策会使用子元素的字面量文本值。

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

默认:

“专有”

状态:

可选

类型:

字符串

<Scope> 设置确定根据 <Scope> 值前置的缓存键。例如,将范围设置为 Exclusive 时,缓存键将采用以下格式:

orgName__envName__apiProxyName__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__proxyEndpointName。

Target

TargetEndpoint 配置用作前缀。

缓存键的前置格式为 orgName__envName__apiProxyName__targetEndpointName。

Exclusive

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

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

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

缓存键的前置格式为 orgName__envName__apiProxyName__proxyNameITargetName

例如,完整的字符串可能如下所示:

apifactory__test__weatherapi__default__apiAccessToken
。

<Source> 元素

指定应将其值写入缓存的变量。

<Source>source_variable</Source>

默认:

不适用

状态:

需要

类型:

字符串

使用说明

将此政策用于通用缓存。在运行时,<PopulateCache> 政策会将您在 <Source> 元素中指定的变量中的数据写入在 <CacheResource> 元素中指定的缓存。您可以使用 <CacheKey>、<Scope> 和 <Prefix> 元素指定可在 <LookupCache> 政策中使用的键,以检索值。使用 <ExpirySettings> 元素配置缓存值应失效的时间。

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

缓存限制:需遵循各种缓存限制,例如名称和值大小、缓存总数、缓存中的项数和过期。

如需详细了解底层数据存储区,请参阅缓存内部。

缓存加密简介

Apigee 和 Apigee Hybrid(1.4 版及更高版本):缓存数据和 KVM 数据始终处于加密状态。

错误代码

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

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP Status 发生的条件
policies.populatecache.EntryCannotBeCached 500 条目无法缓存。要缓存的消息对象不是 Serializable 类的一个实例。

部署错误

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

错误名称 原因 修复
InvalidCacheResourceReference 如果将 PopulateCache 政策中的 <CacheResource> 元素设置为部署 API 代理的环境中不存在的名称,则会出现此错误。
CacheNotFound <CacheResource> 元素中指定的缓存不存在。

故障变量

此政策触发错误时设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。

变量 其中 示例
fault.name="fault_name" fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed policy_name 是抛出故障的政策的用户指定名称。 populatecache.POP-CACHE-1.failed = true

错误响应示例

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

故障规则示例

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>