This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
Configures how the cached values should be purged from the cache.
This policy is intended for use in general purpose short-term caching. It is used in conjunction with the PopulateCache policy (for writing entries) and the LookupCache policy (for reading cache entries).
For caching the responses of backend resources, see the ResponseCache policy.
This policy is an Extensible 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, see Policy types.
Element reference
The following lists the elements you can configure on this policy.
<InvalidateCache async="false" continueOnError="false" enabled="true" name="policy-name"> <DisplayName>Policy Name</DisplayName> <CacheKey> <Prefix>prefix_string</Prefix> <KeyFragment ref="variable_reference"/> <KeyFragment>fragment_string</KeyFragment> </CacheKey> <!-- Omit this element if you're using the included shared cache. --> <CacheResource>cache_to_use</CacheResource> <Scope>scope_enumeration</Scope> <CacheContext> <APIProxyName>application_that_added_the_entry</APIProxyName> <ProxyName>proxy_for_which_data_was_cached</ProxyName> <TargetName>endpoint_for_which_data_was_cached</TargetName> </CacheContext> <PurgeChildEntries>true_to_purge_all_child_entries</PurgeChildEntries> </InvalidateCache>
<InvalidateCache> attributes
The following table describes attributes that are common to all policy parent elements:
Attribute | Description | Default | Presence |
---|---|---|---|
name |
The internal name of the policy. The value of the Optionally, use the |
N/A | Required |
continueOnError |
Set to Set to |
false | Optional |
enabled |
Set to Set to |
true | Optional |
async |
This attribute is deprecated. |
false | Deprecated |
<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>
Default |
N/A If you omit this element, the value of the policy's |
---|---|
Presence | Optional |
Type | String |
<CacheContext>/<APIProxyName> element
Specifies the name of the application that added the cache entry.
<APIProxyName>application_that_added_the_entry</APIProxyName>
Attributes
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref | Variable with the application name. | N/A | Optional | String |
<CacheContext> element
Specifies how to construct a cache key when a Prefix
element value is not
specified, or to clear cache entries added by another API proxy.
<CacheContext> <APIProxyName ref="variable_name">application_that_added_the_entry</APIProxyName> <TargetName ref="variable_name">endpoint_for_which_data_was_cached</TargetName> <ProxyName ref="variable_name">proxy_for_which_data_was_cached</ProxyName> </CacheContext>
Used to construct the CacheKey. Values for APIProxyName, ProxyName, and TargetName are mandatory when a CacheKey prefix (that is, a custom prefix) is not used to clear cache entries added by another API proxy.
<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>
Default: |
N/A |
Presence: |
Required |
Type: |
N/A |
<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.
<CacheResource> element
Specifies the cache where messages should be stored.
Omit this element completely if this policy (and your corresponding PopulateCache and LookupCache policies) is using the included shared cache.
<CacheResource>cache_to_use</CacheResource>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
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 the ref
attribute, or a fixed value.
<KeyFragment ref="variable_name"/> <KeyFragment>literal_string</KeyFragment>
Default: |
N/A |
Presence: |
Optional |
Type: |
N/A |
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, see
Working
with cache keys.
Attributes
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref | The variable from which to get the value. Should not be used if this element contains a literal value. | N/A | Optional | String |
<CacheKey>/<Prefix> element
Specifies a value to use as a cache key prefix.
<Prefix>prefix_string</Prefix>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
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, see
Working
with cache keys.
<CacheContext>/<ProxyName> element
Specifies the name of the proxy for which the data was cached.
<ProxyName>proxy_for_which_data_was_cached</ProxyName>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
Attributes
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref | The variable from which to get the value. Should not be used if this element contains a literal value. | N/A | Optional | String |
<PurgeChildEntries> element
true
to purge cache entries that share the same <Prefix>
value configured for this policy, even if the PopulateCache policy
instances that loaded those items into cache also used various
<KeyFragment>
elements.
Invalidating all of the cache entries of the same prefix value allows you to purge multiple related entries at once.
<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>
Default: |
false |
Presence: |
Optional |
Type: |
Boolean |
<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>
Default: |
"Exclusive" |
Presence: |
Optional |
Type: |
String |
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 for the <Scope>
element are shown below.
For more information, see Working with cache keys.
Acceptable values
Scope Value | Description |
---|---|
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 |
Application |
API proxy name is used as the prefix. Cache key is prepended in the form orgName__envName__applicationName. |
Proxy |
ProxyEndpoint configuration is used as the prefix. Cache key is prepended in the form orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName . |
Target |
TargetEndpoint configuration is used as the prefix. Cache key prepended in the form orgName__envName__applicationName__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:
Cache key prepended in the form orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName For example, the full string might look like this: apifactory__test__weatherapi__16__default__apiAccessToken |
<CacheContext>/<TargetName> element
Specifies the name of the target endpoint for which the data was cached.
<TargetName>endpoint_for_which_data_was_cached</TargetName>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
Attributes
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref | The variable from which to get the value. Should not be used if this element contains a literal value. | N/A | Optional | String |
Usage notes
General purpose caching with the PopulateCache 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 this cache,
simply omit the <CacheResource>
element.
For more about configuring caches, see General purpose caching. For more about the underlying data store, see Cache internals.
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.
Error name | Cause | Fix |
---|---|---|
InvalidCacheResourceReference |
This error occurs if the <CacheResource> element in the InvalidateCache policy is set
to a name that does not exist in the environment where the API proxy is being deployed. |
build |
CacheNotFound |
This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component. | build |
Fault variables
N/A
Example error response
N/A