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> 属性

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

属性	说明	默认	Presence
name	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
continueOnError	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。 设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
async	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

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

<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> 备注： 指定世界协调时间 (UTC) 时区的时间。 Populate Cache 时间表示法遵循国际标准 ISO 8601 中定义的国际标准日期表示法。

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

使用 <ExpirySettings> 的上述每个子元素时，如果您在子元素上指定可选的 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 。

<Source> 元素

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

<Source>source_variable</Source>

默认：	不适用
状态：	必需
类型：	字符串

备注：

• JSON 对象只存储在内存中缓存 (L1) 中。
• 如果您打算在永久性缓存 (L2) 中缓存这些对象，我们建议您将其序列化为字符串格式。
• 通过遵循此实践，您可以有效地利用 L2 缓存并最大限度地提高缓存效率。
• 如需了解详情，请参阅缓存内部。
  

使用说明

将此政策用于通用缓存。在运行时，<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>