Edit

Share via

Get value from cache

APPLIES TO: All API Management tiers

Use the cache-lookup-value policy to perform cache lookup by key and return a cached value. The key can have an arbitrary string value and is typically provided using a policy expression.

Note

This policy must have a corresponding Store value in cache policy.

Important

Built-in cache is volatile and is shared by all units in the same region in the same API Management service.

Note

Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<cache-lookup-value key="cache key value"
    default-value="value to use if cache lookup resulted in a miss"
    variable-name="name of a variable looked up value is assigned to"
    caching-type="prefer-external | external | internal" />

Attributes

Attribute Description Required Default
caching-type Choose between the following values of the attribute:
- internal to use the built-in API Management cache,
- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external to use external cache if configured or internal cache otherwise.

Policy expressions aren't allowed.		 No prefer-external
default-value A value that will be assigned to the variable if the cache key lookup resulted in a miss. If this attribute is not specified, null is assigned. Policy expressions are allowed. No null
key Cache key value to use in the lookup. Policy expressions are allowed. Yes N/A
variable-name Name of the context variable the looked up value will be assigned to, if lookup is successful. If lookup results in a miss, the variable will not be set. Policy expressions aren't allowed. Yes N/A

Usage

Usage notes

  • API Management only caches responses to HTTP GET requests.
  • This policy can only be used once in a policy section.
  • This policy is not supported inside a policy fragment.
  • We recommend configuring a rate-limit policy (or rate-limit-by-key policy) immediately after any cache lookup. This helps keep your backend service from getting overloaded if the cache isn't available.

Example

This example shows how to use the cache-lookup-value policy to retrieve a user profile from the cache. The key for the cache lookup is constructed using a policy expression that combines a string with the value of the enduserid context variable.

Note

The rate-limit policy added after the cache lookup helps limit the number of calls to prevent overload on the backend service in case the cache isn't available.

See a cache-store-value example to store the user profile in the cache.

<cache-lookup-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    variable-name="userprofile" />
<rate-limit calls="10" renewal-period="60" />

For more information and examples of this policy, see Custom caching in Azure API Management.

Related content

For more information about working with policies, see: