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

• Policy sections: inbound, outbound, backend, on-error
• Policy scopes: global, workspace, product, API, operation
• Gateways: classic, v2, consumption, self-hosted

Example

<cache-lookup-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    variable-name="userprofile" />

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

Related policies

• Caching

Related content

For more information about working with policies, see:

• Tutorial: Transform and protect your API
• Policy reference for a full list of policy statements and their settings
• Policy expressions
• Set or edit policies
• Reuse policy configurations
• Policy snippets repo
• Author policies using Microsoft Copilot for Azure