LookupCache policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Configures how cached values should be retrieved at runtime.

This policy is intended for use in general purpose short-term caching. It is used in conjunction with the Populate Cache policy (for writing entries) and the Invalidate Cache policy (for invalidating entries).

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

Element reference

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

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <CacheLookupTimeoutInSeconds/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

A shared cache is included by default. To use the shared cache, omit the <CacheResource> element in this policy configuration.

For more about the underlying data store, see Cache internals. For more about configuring caches, see Creating and editing an environment cache.

<LookupCache> attributes

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

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

<AssignTo> element

Specifies the variable where the cache entry is assigned after it has been retrieved from the cache. The variable must be writable. If the cache lookup doesn't retrieve a value, the variable will not be set.

<AssignTo>variable_to_receive_cached_value</AssignTo>

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

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.

<CacheLookupTimeoutInSeconds> element

Specifies the number of seconds after which an unsuccessful cache lookup will be considered a cache miss. If this occurs, flow resumes along the cache-miss path.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

<CacheResource> element

Specifies the cache where messages should be stored.

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

<CacheResource>cache_to_use</CacheResource>

For more about configuring caches, see Creating and editing an environment cache.

<CacheKey>/<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.

Attributes

<CacheKey>/<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.

<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__applicationName__deployedRevisionNumber__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, see Working with cache keys.

Acceptable values

apifactory__test__weatherapi__16__default__apiAccessToken

Usage notes

Use this policy for general-purpose caching. At runtime, the LookupCache policy retrieves a value from the cache, assigning the value to the variable you specify with the AssignTo element (if no value is retrieved, the variable will not be set). It looks for the value based on a cache key created through configuration that combines the CacheKey and Scope elements. In other words, to retrieve a particular value added to the cache by a PopulateCache policy, your LookupCache policy must have cache key-related elements configured in the same way as the PopulateCache policy.

General purpose caching with the Populate Cache policy, LookupCache policy, and InvalidateCache 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 the default cache, simply omit the <CacheResource> element.

For more about configuring caches, see Creating and editing an environment cache. For more about the underlying data store, see Cache internals.

Flow variables

Flow variables can be used to configure dynamic runtime behavior for policies and flows, based on HTTP headers or message content, or the context available in the Flow. For more information about flow variables, see Variables reference.

The following predefined Flow variables are available after you customize the behavior of the cache you define in a LookupCache policy.

Error codes

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

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

Deployment errors

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

Fault variables

N/A

Example error response

N/A