This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
When using cache policies, you ensure the uniqueness of cached value keys by configuring cache keys. A cache key, along with other values you can configure, gives you a reliable way to get out the same data that you put in. You use cache keys with the PopulateCache policy, LookupCache policy, InvalidateCache policy, and ResponseCache policy.
Apigee uses the values of configuration elements --
<Scope>
,
<CacheKey>
/<Prefix>
, and
<CacheKey>
/<KeyFragment>
-- to compose a
value for the cache key, which is an identifier that is associated with
the value in the cache. Cache key composition works the same way with all of
the cache policies.
With the following cache policy configuration elements, you can create a cache key:
Cache Configuration Element | Description |
---|---|
<Scope> or <CacheKey> /
<Prefix>
|
Use either the <Scope> or the
<CacheKey> <Prefix>
elements to configure a prefix to apply to the final cache key.
<Scope> enumerates a list of predefined values. The
<CacheKey> <Prefix> element
overrides <Scope> with a fixed value of your own
choosing.
|
<CacheKey> / <KeyFragment> |
Use one or more <CacheKey>
<KeyFragment> elements combined to specify a unique
identifier for cache entries. KeyFragment values can be static literals
or set from variables.
|
Apigee composes the cache key of two parts, the prefix part and the composite fragment part, separated by a double-underscore.
PREFIX_PART__FRAGMENT_PART
The prefix part is determined by the <Scope>
element, or
the <CacheKey>
<Prefix>
element if it is
present. The fragment part is composed of each of the values from each
<KeyFragment>
element, joined by double-underscores.
With the Response Cache policy, you can optionally append this cache key with values from the response Accept header.
Using <CacheKey>
The <CacheKey>
element configures how Apigee will create a
unique identifier (a key) for each cache entry it creates. When Apigee
retrieves the cached value, it uses the cache key to locate the correct value.
In the ResponseCache policy, one configuration defines the key for both
caching and retrieval. In the PopulateCache and LookupCache policies, each
policy must have identical <CacheKey>
elements to ensure
that a value retrieved from the cache corresponds to a value put there.
The <CacheKey>
element can include a single optional
<Prefix>
element as well as one or more
<KeyFragment>
elements. At runtime, Apigee concatenates the
values determined from each part two underscores between them to make up the
cache key.
For example, the following configuration creates a value of
myprefix__hello__world
for use in the cache key:
<CacheKey> <Prefix>myprefix</Prefix> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>
You can configure Apigee to use a dynamically composed cache key by
referencing the variable in a <KeyFragment>
element, as
shown here:
<KeyFragment ref="variable_name"/>
For example, to make the cache key value incorporate the Content-Type of the request message, you do as follows:
<KeyFragment ref="request.header.Content-Type"/>
Consider the following configuration:
<CacheKey> <Prefix>system1</Prefix> <KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.header.Content-Type" /> <KeyFragment>bar</KeyFragment> </CacheKey>
If the request.header.Content-Type
variable has the value
application/json
, this will result in a cache key of
system1__apiAccessToken__application/json__bar
.
You can use platform-defined or custom variables in a
ref
attribute.
Cache keys derived from query parameters
Using variables such as request.queryparam.<queryparam_name> and request.querystring, you can configure a cache key so that the key includes parts of a request's query string. For example, the following URL uses two query parameters -- param1 and param2 -- that you can use in your cache key:
http://myaccount.apigee.net/mydata?param1=value1¶m2=value2
Your <CacheKey>
element can incorporate these values with a
configuration such as the following:
<CacheKey> <KeyFragment ref="request.queryparam.param1" /> <KeyFragment ref="request.queryparam.param2" /> <CacheKey>
At runtime, the cache key would include the param values concatenated, as in the following:
prefix_part__value1__value2
Rather than specifying multiple distinct query parameters, an alternative is
to use the request.querystring
variable, which inserts the entire
string of parameters literally as part of the cache key. Keep in mind that
while this method accounts for all of the parameters, if the order of
parameters varies from one request to the next then the key will be different.
In other words, param1=value1¶m2=value2
and
param2=value2¶m1=value1
don't result in the same cache
key value.
Using <Scope> and <Prefix>
The <Scope>
and <CacheKey>
/
<Prefix>
elements provide a way to organize cached values
into a namespace. Apigee prepends a value derived from them to your cache key.
The advantage of using a scope or prefix in your cache key is that you can
invalidate all the values that share a single prefix, with one call to the
InvalidateCache policy.
The <Scope>
element is used by default. It is an
enumeration whose values range from broad to narrow, with the narrowest as the
default. This default value is used unless you specify another value or
specify a <Prefix>
element value. You can override the
<Scope>
value by using a <CacheKey>
/
<Prefix>
element, and so specify a custom value for
namespacing.
For example, the <Scope>
value "Global" -- the broadest
scope -- represents the organization and environment name. So if your proxy is
deployed in an organization called 'mycompany' and an environment named
'prod', the resulting preprended value will be the following:
mycompany__prod__[FRAGMENT_PART]
As described in LookupCache policy, the scope can be configured for increasing specificity from Global to Exclusive. An Exclusive scope is the most specific, and therefore represents minimal risk of namespace collisions within a given cache. Each cache entry with an Exclusive scope is prefixed in the following form:
orgName__envName__apiProxyName__deployedRevisionNumber__nameof(proxyEndpoint|targetEndpoint)__[serializedCacheKey]
Some examples follow. These assume that the 16th revision of your proxy named 'weatherapi' is deployed in an organization called 'mycompany' and an environment named 'prod', and the proxyEndpoint name is 'default', and that the cache policy is attached to a flow in the proxyEndpoint.
Configuration | Result |
---|---|
<Scope>Global</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey> |
mycompany__prod__hello__world . |
<Scope>Exclusive</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey> |
mycompany__prod__weatherapi__16__default__hello__world |
<Scope>Exclusive</Scope> <CacheKey> <Prefix>system1</Prefix> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey> |
system1__hello__world |