This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The PopulateCache policy configures how cached values should be written at runtime.

The Populate Cache policy is designed for writing entries in a short-term general-purpose cache. It's used in conjunction with theLookup Cache policy (for reading cache entries) and theInvalidate Cache policy (for invalidating entries).

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

For caching the responses of backend resources, see theResponse Cache policy.

Element reference

The following lists the elements you can configure on this policy.

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

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

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>

<CacheKey> element

Configures a unique pointer to a piece of data stored in the cache.

Cache keys are limited to a size of 2 KB.

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

<CacheKey> constructs the name of each piece of data stored in the cache.

At runtime,<KeyFragment> values are prepended with either the<Scope> element value or<Prefix> value. For example, the following results in a cache key ofUserToken__apiAccessToken__<value_of_client_id>:

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

You use the<CacheKey> element in conjunction with<Prefix> and<Scope>. For more information, seeWorking with cache keys.

<CacheResource> element

Specifies the cache where messages should be stored.

Omit this element completely if this policy (and your corresponding LookupCache and InvalidateCache policies) is using the included shared cache.

<CacheResource>cache_to_use</CacheResource>

For more about configuring caches, see General purpose caching.

<CacheKey>/<KeyFragment> element

Specifies a value that should be included in the cache key. Specify a variable to de-reference with theref attribute, or a fixed value.

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

At runtime, Apigee creates the cache key by prepending the value obtained from the<Scope> element or the<Prefix> element, to a concatenation of the resolved values of each of the<KeyFragment> elements. For more information, seeWorking with cache keys.

Attributes

<CacheKey>/<Prefix> element

Specifies a fixed value to use as a cache key prefix.

<Prefix>prefix_string</Prefix>

A<Prefix> element overrides any<Scope> element.

At runtime, Apigee creates the cache key by prepending the value obtained from the<Scope> element or the<Prefix> element, to a concatenation of the resolved values of each of the<KeyFragment> elements. For more information, seeWorking with cache keys.

<ExpirySettings> element

Specifies when a cache entry should expire.

<ExpirySettings><!--useexactlyoneofthefollowingchildelements--><TimeoutInSecondsref="duration_variable">seconds_until_expiration</TimeoutInSeconds><ExpiryDateref="date_variable">expiration_date</ExpiryDate><TimeOfDayref="time_variable">expiration_time</TimeOfDay></ExpirySettings>

Child elements of<ExpirySettings>

Use exactly one child element. The following table provides a description of the child elements of<ExpirySettings>:

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

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

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

You should specify only one of the possible child elements. If you specify multiple elements, the order of precedence is:TimeoutInSeconds,ExpiryDate,TimeOfDay.

With each of the above child elements of<ExpirySettings>, if you specify the optionalref attribute on the child element, the policy will retrieve the expiry value from the named context variable. If the variable is not defined, the policy uses the literal text value of the child element.

<Scope> element

Enumeration used to construct a prefix for a cache key when a<Prefix> element is not provided in the<CacheKey> element.

<Scope>scope_enumeration</Scope>

The<Scope> setting determines a cache key that is prepended according to the<Scope> value. For example, a cache key would take the following form when scope is set toExclusive:

orgName__envName__apiProxyName__proxy|TargetName__ [serializedCacheKey ]

If a<Prefix> element is present in<CacheKey>, it supersedes a<Scope> element value. Valid values include the enumerations below.

You use the<Scope> element in conjunction with<CacheKey> and<Prefix>. For more information, seeWorking with cache keys.

Acceptable values

apifactory__test__weatherapi__default__apiAccessToken

<Source> element

Specifies the variable whose value should be written to the cache.

<Source>source_variable</Source>

• JSON objects are exclusively stored in thein-memory cache (L1).
• If you intend to cache these objects inpersistent chache (L2), we recommend serializing them into astring format.
• By following this practice, you can effectively utilize the L2 cache and maximize caching efficiency.
• For more information, seeCache internals.
  

Usage notes

Use this policy for general purpose caching. At runtime, the<PopulateCache> policy writes data from the variable you specified in the<Source> element to the cache you specified in the<CacheResource> element. You can use the<CacheKey>,<Scope>, and<Prefix> elements to specify a key that you can use from the<LookupCache> policy to retrieve the value. Use the<ExpirySettings> element to configure when the cached value should expire.

General purpose caching with the PopulateCache policy,LookupCache policy, andInvalidateCache policy uses either a cache you configure or a shared cache that's included by default. In most cases, the underlying shared cache should meet your needs. To use this cache, simply omit the<CacheResource> element.

Cache limits:Various cache limits apply, such as name and value size, total number of caches, the number of items in a cache, and expiration.

For more about the underlying data store, seeCache internals.

About cache encryption

Apigee and Apigee hybrid (version 1.4 and later): Cache and KVM data are always encrypted.

Error codes

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, seeWhat you need to know about policy errors andHandling 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.

These variables are set when this policy triggers an error. For more information, seeWhat 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>