PopulateCache 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

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

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

如需了解如何缓存后端资源的响应，请参阅 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> 属性

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

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

指定应在缓存键中包含的值，从而创建用于将请求与缓存响应匹配的命名空间。

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

这可以是键（您提供的静态名称）或值（通过引用变量设置的动态条目）。组合的所有指定片段（加上前缀）都串联在一起以创建缓存键。

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

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

属性

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

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

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

<ExpirySettings> 元素

指定缓存条目何时失效。如果存在，<TimeoutInSeconds> 将同时替换 <TimeOfDay> 和 <ExpiryDate>。

<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> 的子元素相关的说明：

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

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

<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__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

如果 <CacheKey> 中存在 <Prefix> 元素，则它会取代 <Scope> 元素值。有效值包括以下枚举。

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

可接受的值

apifactory__test__weatherapi__16__default__apiAccessToken

<Source> 元素

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

<Source>source_variable</Source>

使用说明

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

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

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

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

缓存加密简介

适用于公有云的 Edge：缓存仅在 PCI- 且符合HIPAA 计划 组织。这些组织的加密会在组织预配期间进行配置。

错误代码

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

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