Was this helpful?

Configures how cached values should be written at runtime.

<PopulateCache async="false" continueOnError="false" enabled="true" name="policy-name">
    <DisplayName>policy_name</DisplayName>
    <FaultRules>rules_for_fault_handling</FaultRules>
    <Properties>property_elements</Properties>
    <CacheKey>
        <Prefix>prefix_string</Prefix>
        <KeyFragment ref="variable_reference"/>
        <KeyFragment>fragment_string</KeyFragment>
    </CacheKey>
    <CacheResource>cache_to_use</CacheResource>
    <Scope>scope_enumeration</Scope>
    <ExpirySettings>
        <TimeoutInSec>number_of_seconds_until_expiration</TimeoutInSec>
        <TimeOfDay>expiration_time</TimeOfDay>
        <ExpiryDate>expiration_date</ExpiryDate>
    </ExpirySettings>
    <Source>variable_holding_data_to_cache</Source>
</PopulateCache>

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.

Your organization comes with a default cache. For more about the underlying data store, see Why Use a Cache?. For more about configuring caches, see Manage caches for an environment.

PopulateCache children

Element Required Default Description
<DisplayName> No   Captures the policy’s function with a short, intuitive name.
<FaultRules> No   Configures fault handling for the policy. For more on fault handling, see Fault handling or Policy attachment and enforcement.
<Properties> No   Specifies property/value pairs that configure specific behavior.
<CacheKey> Yes   Configures a unique pointer to a piece of data stored in the cache.
    <Prefix> No   Specifies a value to use as a cache key prefix.
    <KeyFragment> No   Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.
<CacheResource> Yes   Specifies the cache where messages should be stored. A default cache is available.
<Scope> Yes Exclusive Enumeration used to construct a prefix for a cache key when a <Prefix> element is not provided in the <CacheKey> element.
<ExpirySettings> Yes   Specifies when the cached value should expire.
    <ExpiryDate> No   Specifies the date on which a cache entry should expire. Use the form mm-dd-yyyy
    <TimeOfDay> No   The time of day at which a cache entry should expire. Use the form hh:mm:ss
    <TimeoutInSec> No   The number of seconds after which a cache entry should expire.
<Source> Yes   Specifies the variable whose value should be written to the cache.

PopulateCache attributes

Attribute Type Default Required Description
async boolean false No

true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

continueOnError boolean false No

true to specify that flow execution should continue on a failure. Default is false.

Most policies are expected to return an error when a failure occurs (for example, when a quota is exceeded).

name string   No

Specifies the name of the policy, which is referenced in step elements to attach the policy to a flow. Characters you can use in the name are restricted to: A-Z0-9._\-$ %.


CacheKey element

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

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

<CacheKey> constructs the name of each piece of data stored in the cache. The cache key you define in the <PopulateCache> policy is the name that you use in the <LookupCache> policy to get the specific entry that you need from 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 of UserToken__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, see Working with cache keys.

CacheKey children

Element Required Default Description
<Prefix> No   Specifies a value to use as a cache key prefix.
<KeyFragment> No   Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.

Prefix element

Specifies a value to use as a cache key prefix.

<Prefix>prefix_string</Prefix>

Use this value instead of <Scope> when you want to specify your own value rather than a <Scope> -enumerated value. If defined, <Prefix> prepends the cache key value for entries written to the cache. A <Prefix> element value overrides a <Scope> element value.

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


KeyFragment element

Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.

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

This can be a key (a static name that you provide) or a value (a dynamic entry set by referencing a variable). All specified fragments combined (plus the prefix) are concatenated to create the cache key.

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

You use the <KeyFragment> element in conjunction with <Prefix> and <Scope>. For more information, see Working with cache keys.

KeyFragment attributes

Attribute Type Default Required Description
ref string   No

The variable from which to get the value. Should not be used if this element contains a literal value.


CacheResource element

Specifies the cache where messages should be stored. A default cache is available.

<CacheResource>cache_to_use</CacheResource>

For more about configuring caches, see Manage caches for an environment.


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 to Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

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

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

Scope values

Global

Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the form  orgName __ envName __.

If you define a <CacheKey> entry with the <KeyFragment> apiAccessToken and a <Global> scope, each entry is stored as orgName__envName__apiAccessToken, followed by the serialized value of the access token. For an API proxy deployed in an environment called 'test' in an organization called 'apifactory', access tokens would be stored under the following cache key: apifactory__test__apiAccessToken.

APIProxy

API proxy name is used as the prefix.

Cache key is prepended in the form orgName__envName__apiProxyName.

Proxy

ProxyEndpoint configuration is used as the prefix.

Cache key is prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName .

Target

TargetEndpoint configuration is used as the prefix.

Cache key prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName .

Exclusive

Default. This is the most specific, and therefore presents minimal risk of namespace collisions within a given cache.

Prefix is one of two forms:

  • If the policy is attached to the ProxyEndpoint flow, prefix is of the form ApiProxyName_ProxyEndpointName.
  • If the policy is attached at TargetEndpoint, prefix is of the form ApiProxyName_TargetName.

Cache key prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

For example, the full string might look like this:

apifactory__test__weatherapi__16__default__apiAccessToken
.

ExpirySettings Element

Specifies when a cache entry should expire.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

CacheKey children

Element Required Default Description
<ExpiryDate> No   Specifies the date on which a cache entry should expire. Use the form mm-dd-yyyy
<TimeOfDay> No   The time of day at which a cache entry should expire. Use the form hh:mm:ss
<TimeoutInSec> No   The number of seconds after which a cache entry should expire.

TimeOfDay Element

The time of day at which a cache entry should expire. Use the form hh:mm:ss .

<TimeOfDay ref="time_variable">expiration_time</TimeOfDay>

Attributes

Attribute Type Default Required Description
ref string   No

Variable with the expiration time value.


TimeoutInSec Element

The number of seconds after which a cache entry should expire.

<TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>

Attributes

Attribute Type Default Required Description
ref string   No

Variable with the timeout value.


ExpiryDate Element

Specifies the date on which a cache entry should expire. Use the form mm-dd-yyyy .

<ExpiryDate ref="date_variable">expiration_date</ExpiryDate>

Attributes

Attribute Type Default Required Description
ref string   No Variable with the expiration date value.

Source Element

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

<Source>source_variable</Source>

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)