Feature Overview

A cache key is the unique ID of a cached file on a CDN point of presence (POP). Each cached file on a CDN POP corresponds to a cache key. By default, the cache key of a file is the original URL (including a query string) of the request that is sent from a client to access the file.

You can configure a custom cache key for requests that are sent using different URLs but point to the same file. This helps you increase the cache hit ratio and reduce the number of origin requests.

Application Scenarios

In some cases, a CDN POP may receive requests with different URLs that point to an identical file. In such a case, you can enable the custom cache key feature to point the requests to the same cached file, which helps improve cache hit ratio.

For example, if you set a string for hotlink protection in request URL. The string may be included in the query string or as a part of the path in the URL. Assume that a CDN POP receives request 1 whose URL is http://www.example.com/xxxxx/test/a.mp4 and request 2 whose URL is http://www.example.com/yyyyy/test/a.mp4. Because the URLs are different, the CDN POP considers that different files are requested by default and caches different MP4 files. However, the two request URLs point to the same file because their first layer path are strings for hotlink protection. In this case, you can customize the cache URI to set the cache key to http://www.example.com/test/a.mp4 so that only one file is cached.

Procedure

Cache Parameters

Log in to the CDN console.
Go to Domain Management -> Domain List page.
On the Domain List page, find the target domain name, and click Edit in the Actions column.
Click Cache .
Click Cache Keys tab.
Click Add underneath Cache Parameter section and setup cache parameters as you need.

Items	Value	Descriptions
Type	File extension/Directory/Homepage/All files/Absolute file path	Select target files types.
Content	Specify particular contents under the selected type	You need to specify the contents if you select File extension/directroy/absolute file path as the Type, for example, when the type is set to file extension, you need to clarify the explicit file extensions at here, when the type is set to directory, you need to clarify the actual path of the directory.
Ignore parameters	Not Ignore/Ignore all/Retain specified parameters/Ignore specified parameters	Cache parameters settings. 1. Select Not Ignore represents keep all the query string parameters as cache keys. 2. Ignore all represents none of the query string parameters will be used as cache keys. 3. Retain specified parameters, represents only the specified query string parameters will be used as cache keys. 4. Ignore specified parameters, represents other parameters will be used as cache keys rather than the specified ones. For the specified parameters, character "-" hyphen is not supported in the parameter name, for example, a-b, if you need, please contact our customer support team via hotline (852)31000000 or email global.noc@chinatelecomglobal.com for help.
Priority	Numerics	When there are multiple cahce rules for the same file type or content, the rules with higher priority will be applied.

Cache URI

Log in to the CDN console.
Go to Domain Management -> Domain List page.
On the Domain List page, find the target domain name, and click Edit in the Actions column.
Click Cache .
Click Cache Keys tab.
Click Add underneath Cache URI section and setup cache rules as you need.
Click OK and Save.

Items	配置值	说明
Path to be rewritten	The URI to be rewritten	The URI starts with a forward slash (/) and does not contain http:// or the domain name, ? or parameters. Regular expressions are supported, e.g. ^/test$.
Target path	The URI after rewrite	The URI starts with a forward slash (/) and does not contain http:// or the domain name, ? or parameters. Regular expressions are supported. $1 and $2 are commonly used to capture the strings in parentheses (()) in the Path to be overwritten.

Examples

Retain specified parameters

Applicable scenario：

End user request URL：http://www.example.com/a/a.html?a=1&c=2&d=3。

When http://www.example.com/a/a.html?a=1&c=2&d=3 and http://www.example.com/a/a.html?a=1&c=4&d=5 point to the same file at origin.

Meanwhile, http://www.example.com/a/a.html? a=1 &c=2&d=3 and http://www.example.com/a/a.html?**a=2**&c=4&d=5 point to different files at origin.

In this case, you can configure retain parameter a as the cache key. Then http://www.example.com/a/a.html?a=1&c=2&d=3 and http://www.example.com/a/a.html?a=1&c=4&d=5 will be cahed as http://www.example.com/a/a.html?a=1。

Notes:

To ensure the cache on CDN work properly, if there are any other parameters rather than parameter a would affect the contents, please also keep those parameters as cache keys.

Ignore specified parameters

Applicable scenario：

When only the query string parameter d will not affect the content, which means http://www.example.com/a/a.html?b=1&c=2&d=3 and http://www.example.com/a/a.html?b=1&c=2&d=5 are pointing to the same content, and the rest of the query strings in the URL will be treated as cache keys, you can configure to ignore parameter d, the prior two URLs will be cached as http://www.ctyun.cn/a/a.html?b=1&c=2.

Cache URI rewrite

Ingore the first layer of the path when caching, for example, the original request is /a/b/c.mp4, the URI after rewrite will be /b/c.mp4.

Additional Considerations

By default, the ignore query strings when caching feature is enabled in Domain Management > Cache in the CDN console. After this feature is enabled, if the client request URLs include multiple parameter values, such as http://www.test.com/a.mp4?a=1 and http://www.test.com/a.mp4?a=2, the cache keys corresponding to the requests are unified as http://www.test.com/a.mp4. This way, the two requests hit the same cached file, thereby reducing the back-to-origin rate. If the ignore query strings when caching feature can meet your requirements for custom cache keys, you can enable the feature in the CDN console with no need to submit a ticket to enable the custom cache key feature.
If both the custom cache key feature and the ignore query strings when caching feature (in Domain Management > Cache in the CDN console) are enabled at the same time, the custom cache key feature takes prevalence.
We recommend that you do not change your custom cache key setting without careful consideration. If you change the custom cache key setting after it takes effect, the cache entries that are generated based on the original custom cache key setting become invalid, which can result in a large number of back-to-origin requests.
The custom cache key feature takes effect only for cache keys on CDN POPs and does not affect back-to-origin operations performed by CDN POPs. Even if you specify a cache URI or configure CDN to retain or ignore specific parameters in the cache key, whether to rewrite URIs or carry the corresponding parameters in the back-to-origin routing process are determined based on the configurations of the back-to-origin URI rewrite feature and the back-to-origin parameter rewrite feature. For more information, see Configuring Back-to-origin URI Rewrite and Configuring Back-to-origin Parameter Rewrite.
If you need to setup cache by request protocol or cache host, pplease contact our customer support team via hotline (852)31000000 or email global.noc@chinatelecomglobal.com.

Content Delivery Network

Cache key settings