Custom cache key-Edge Security Acceleration(ESA)-阿里云帮助中心

Usage notes

Custom cache key and Ignore Parameters

The Parameter Operations feature of a custom CacheKey and the Ignore Parameters feature both control whether URL query parameters are included in cache key generation. Enabling both features at the same time may cause conflicts in cache key generation rules, resulting in a lower cache hit ratio or abnormal cached content.

Important

If you use parameter operations for custom cache keys, disable the Ignore Parameters feature to prevent rule conflicts. The parameter operations include the functionality of the Ignore Parameters feature (through the Delete or Reserve operations) and offer more flexible parameter control.

If you use the Ignore Parameters feature, refer to the following table to decide whether to switch to parameter operations for custom cache keys.

Scenario	Ignore Parameters	Custom cache key
Ignore all query parameters in the cache key	Set Ignore Parameters to Yes and leave Keep specified parameters empty.	Add a processing rule for query parameters: Operation: Keep Parameter Name: Set to any non-existent parameter name, such as `example-argument`.
Keep only the query parameter `key1` in the cache key	Set Ignore Parameters to Yes and set Keep specified parameters to `key1`.	Add a processing rule for query parameters: Operation: Keep Parameter Name: `key1`
Delete only the query parameter `key1` from the cache key	Set Delete specified parameters to `key1`.	Add a processing rule for query parameters: Operation: Delete Parameter Name: `key1`

Note

If you need to further modify parameter values or add extra parameters beyond ignoring or keeping them, use the parameter operations for custom cache keys instead of the Ignore Parameters feature.

Rules engine execution order

Note

When this feature references a Rule Condition from the Rules Engine, the execution order is based on the priority of the Rule Condition in the Rules Engine, not the priority of rules configured within this feature.

Cache refresh

After you configure a custom cache key, DCDN PoPs index cached files by the processed cache key. When you refresh the cache by URL, submit the URL that matches the cache key on the DCDN PoPs. Otherwise, the refresh operation cannot find the target content.

Note

For example, if you configure a URI replacement rule to replace /a/b/image.jpg with /c/image.jpg, the cache key for the file on DCDN PoPs becomes http://aliyundoc.com/c/image.jpg. To refresh this file's cache, you must submit http://aliyundoc.com/c/image.jpg (the processed cache key), not the original client request URL.

If you configure parameter operations such as deleting or modifying parameters, use the processed URL as the refresh address. Record the final cache key format after configuring custom cache key rules to simplify future cache refresh operations.

Origin URL rewrite

The custom cache key feature only affects how cache keys are generated on DCDN PoPs. It does not modify the actual URL used for origin fetches. When a DCDN PoP fetches from the origin, it uses the original client request URL. To rewrite the parameters or path of the request sent to the origin, use the origin URL rewrite feature.

Note

For example, a client requests http://example.com/image.jpg?key1=1&key2=2. You configure a custom cache key to delete the key1 parameter. The cache key becomes http://example.com/image.jpg?key2=2. However, when the DCDN PoP fetches from the origin, it still requests the original URL: http://example.com/image.jpg?key1=1&key2=2.

Use cases

Important

The custom cache key feature does not modify the URL used for origin fetches. It only changes the cache identifier for the request. The request sent to the origin remains identical to the original client request.

A cache key is the unique identifier for a file cached on a DCDN PoP. By default, the cache key is the complete request URL, including query parameters.

Scenario 1

When client requests for the same file contain different URL parameters, DCDN PoPs treat them as requests for different files. This results in multiple cached copies of the same file and increases origin fetches.

You can use custom cache key rules to unify the cache keys for similar requests, reducing the origin fetch rate.

Scenario 2

DCDN treats requests with the same URL as requests for the same file. However, the HTTP header of the request contains a client field to differentiate between client systems, and the goal is to retrieve different files. Scenario 1

In this case, you can use a custom Cachekey to append the value of the client field to the Cachekey. The two requests are then identified as two different Cachekeys. Scenario 2

Procedure

Log on to the DCDN console.
In the left-side navigation pane, click Domain Names.
On the Domain Names page, find the target domain name and click Configure.
In the left-side navigation tree of the domain name, click Caching.

On the Custom Cache Key tab, configure the Cache Key.

Note

The final cache key is a combination of the following four components: URI, Parameter Actions, HTTP Headers, and Custom Variables.

自定义Cachekey

Parameter	Description
Rule Condition	A rule condition determines whether a configuration applies to a request by evaluating parameters in the request. Important When a feature references rule conditions configured in the rules engine, the execution order follows the priority of the associated rule conditions, not the order of the feature configurations. Do not use conditions: Disables conditional rules. You can add or edit conditional rules in Rules engine.
URIs	If the URI of a client request matches the configured Source URI, the system replaces the Source URI with the configured Final URI when generating the URI part of the cache key. You can configure multiple URI replacement rules. If multiple rules exist, they are matched sequentially from top to bottom. Once a Source URI is matched, the system uses the corresponding Final URI for the replacement and stops matching subsequent rules. Source URI: A URI that starts with a forward slash (/), not including the http:// prefix or the domain name. Supports `PCRE` regular expressions. Final URI: A URI that starts with a forward slash (/) and does not contain the http:// prefix or a domain name.
Parameter Actions	These operations apply to the query parameters in the original request URL. You can perform Add, Delete, Modify, or Reserve operations on the parameters. The resulting parameters form the query string part of the cache key. You can configure multiple operations, which are executed sequentially from top to bottom. Add: Appends a new query parameter to the cache key. For example, if the original URL is `http://image.example.com/cat.jpg` and you add the query parameter `type=jpg`, the cache key becomes `http://image.example.com/cat.jpg?type=jpg`. Delete: Removes a specified query parameter from the original request URL when the cache key is generated. For example, if the original URL is `http://image.example.com/cat.jpg?type=jpg` and you delete the `type` parameter, the cache key becomes `http://image.example.com/cat.jpg`. Modify: Modifies a specified query parameter in the original request URL when the cache key is generated. For example, if the original URL is `http://image.example.com/cat.jpg?type=jpg` and you modify the parameter to `type=png`, the cache key becomes `http://image.example.com/cat.jpg?type=png`. Reserve: Keeps only specified query parameters from the original request URL when the cache key is generated. For example, if the original URL is `http://image.example.com/cat.jpg?type=jpg&path=image` and you keep the `type` parameter, the cache key becomes `http://image.example.com/cat.jpg?type=jpg`.
HTTP Headers	Appends the value of a specified HTTP header from the original client request to the cache key. You can configure multiple HTTP header names, separated by spaces. The value of each specified HTTP header is appended to the cache key sequentially. For example, if the original URL is `http://image.example.com/cat.jpg` and the client request includes an HTTP header `path: image`, and you set the HTTP Headers setting to include the `path` header, the cache key becomes `http://image.example.com/cat.jpgimage`.
Custom Variables	You can use regular expressions to match the value of a specified query parameter, HTTP header, cookie parameter, or URI from the original client request. If a match is found, the value is appended to the cache key. For details, see Configuration examples.

Click OK to complete the configuration.

Configuration examples

URIs

Requests for http://aliyundoc.com/a/b/image.jpg and http://aliyundoc.com/a/b/c/image.jpg are treated as requests for the same file. The cache key for this file is http://aliyundoc.com/c/image.jpg.

Parameter Actions

For a client request to http://aliyundoc.com/a/b/image.jpg?delete_par=1&modify_par=1 , the rules add add_par=1, delete delete_par, and modify the value of modify_par to 2. The final cache key is http://aliyundoc.com/a/b/image.jpg?modify_par=2&add_par=1.

Important

For parameter operations, if multiple operations are applied to the same variable, the priority of the operations is as follows: Add > Delete > Keep > Modify.

HTTP Headers

The values of the User-Agent and Accept-Language HTTP headers from the client request are appended to the cache key. For a request to http://aliyundoc.com/a/b/image.jpg with User-Agent: Mozilla/5.0 (Linux; X11) and Accept-Language: en, the resulting cache key is http://aliyundoc.com/a/b/image.jpgMozilla/5.0(Linux;X11)en.

Custom Variables

Example 1

The variable name is language, the source is Request Header, the source field name is Accept-Language, the matching pattern is ([%w]+),([%w]+), and the variable expression is $1aa.

If a client sends a request for http://aliyundoc.com/a/b/image.jpg with the HTTP request header Accept-Language=en,ch , the matching pattern matches en and assigns it to $1 in the variable expression. The variable expression then appends aa to create the value enaa. This value is aliased as language and appended to the URL to form the cache key: http://aliyundoc.com/a/b/image.jpgenaa.

Note

In a variable expression, $n represents the content captured by the nth pair of parentheses in the matching pattern. For example, in Example 1, if the input is Accept-Language=en,ch and the matching pattern is ([%w]+),([%w]+), then $1=en and $2=ch.

Example 2

The variable name is expired, the source is Request Cookie, the source field name is a, the matching pattern is [%w]+:(.*), and the variable expression is $1.

If a client requests http://aliyundoc.com/a/b/image.jpg with the cookie Cookie a=expired_time:12635187, the matching pattern matches 12635187. This value is assigned to $1 in the variable expression with the alias expired, and is appended to the URL to form the final Cachekey: http://aliyundoc.com/a/b/image.jpg12635187.

Example 3

Configure both URI rules and custom variables.

URI:

Rewrite all request URIs matching /abc/.*/abc to /abc.
Custom Variable:

The variable name is testname, the source is Path, the matching pattern is /abc/xyz/(.*), and the variable expression is $1.

For a client request with the URL http://aliyundoc.com/abc/xyz/abc/image.jpg, the Cache Key is normalized to http://aliyundoc.com/abc/image.jpg based on the URI configuration. Then, based on the Custom Variable configuration, this URL matches /abc/xyz/(.*), at which point $1 is assigned the value abc and appended to the Cache Key to form the final Cache Key: http://aliyundoc.com/abc/image.jpgabc. This allows the two rules to work together to implement more complex caching logic.

If a custom variable for the CacheKey is not matched, the variable expression $1 will not be concatenated to the CacheKey.