CacheKey Object

The cacheKey object contains methods to modify a cacheKey for an HTTP request.

The cacheKey request object contains properties that optimize cached delivery by defining unique cached content. Unique cached content is typically a combination of the URL, query arguments, cookies, headers, or custom variables. cacheKey optimization ensures that the correct cached content is delivered and ultimately improves offload and performance.

The cacheKey request object contains properties specific to a given request. The properties include excludeQueryString(), includeQueryString(), includeQueryArgument(name), includeCookie(name), includeHeader(name), and includeVariable(name). CacheKey request objects can only be modified during the onClientRequest event.

For more information about how to purge EdgeWorker generated cacheKey modifications see Purge Methods.

When using the Fast Purge API a 403 error will occur if the URL includes an EdgeWorker with request.respondWith functionality. To avoid this error, wrap the respondWith() method with a condition to prevent its execution for the AKAMAI_TRANSLATE method. For example, if (request.method != "AKAMAI_TRANSLATE" ){ … }

To learn more log in to Akamai Community and review the API-gives-403-unauthorized-arl-error article.

excludeQueryString()

Sets the query string to exclude from the cache key.

Note: If you have URLs that yield different responses based on a unique path or query string, make sure you don’t exclude these differences in the cache key.
// GET /search?q=something
// Host: www.example.com
request.cacheKey.excludeQueryString();
// X-True-Cache-Key: /X/XXX/www.example.com/search

includeQueryString()

Sets the query string to be included as part of the cache key. This is done by default, however it is provided as an API to be reverted to the default. 

// GET /search?q=something
// Host: www.example.com 
request.cacheKey.includeQueryString();
// X-True-Cache-Key: /X/XXX/www.example.com/search?q=something

includeQueryArgument(name)

Sets a query argument to be included as part of the cache key. Can be called multiple times to include multiple query arguments. Calling this function at least once will result in all query arguments not explicitly included to be excluded from the cache key. By default, the entire query string is part of the cache key. This function takes precedence over "excludeQueryString()". If both are called only the query parameters named in the "includeQueryArgument" property become part of the cache key.

Review the table for information about the possible arguments.

Argument Description Object Type
name Name of the query argument to include in the cache key String 
// GET /search?q=something&r=somethingelse&s=nextthing
// Host: www.example.com
request.cacheKey.includeQueryArgument('q');
// X-True-Cache-Key: /X/XXX/www.example.com/search?q=something 
// GET /search?q=something&r=somethingelse&s=nextthing
// Host: www.example.com
request.cacheKey.includeQueryArgument('q');
request.cacheKey.includeQueryArgument('s');
// X-True-Cache-Key: /X/XXX/www.example.com/search?q=something&s=nextthing

includeCookie(name)

Sets a cookie in the cache key. Can be called multiple times to include multiple cookies.

Note: You can only add cookies from an end user generated request. Cookies created in Property Manager or using setHeader in EdgeWorkers cannot be added into the cache key.
Review the table for information about the possible arguments.
Argument Description Object Type
name Name of the Cookie to include in the cache key String 
// GET /search
// Host: www.example.com
// Cookie: cookie1=value1;cookie2=value2;cookie3=value3
request.cacheKey.includeCookie('cookie1');
// X-True-Cache-Key: /X/XXX/www.example.com/search cid=_cookie1=value1_

includeHeader(name)

Sets an HTTP request header in the cache key. Can be called multiple times to include multiple headers.

Note: You can only add headers from an end user generated request. Headers created in Property Manager or using setHeader in EdgeWorkers cannot be added into the cache key.

Review the table for information about the possible arguments.

Argument Description Object Type
name Name of the HTTP request header to include in the cache key String 
// GET /search
// Host: www.example.com
// X-MyHeader: MyValue
request.cacheKey.includeHeader('X-MyHeader');
// X-True-Cache-Key: /X/XXX/www.example.com/search cid=_X-MyHeader=MyValue_

includeVariable(name)

Sets a Property Manager user-defined variable in the cache key. Can be called multiple times to include multiple variables.

Review the table for information about the possible arguments.

Argument Description Object Type
name Name of the Property Manager user-defined variable. Only variables that start with a PMUSER prefix are available. String 
// GET /search
// Host: www.example.com
request.cacheKey.includeVariable('PMUSER_MYVARIABLE');
// X-True-Cache-Key: /X/XXX/www.example.com/search cid=_PMUSER_MYVARIABLE=MYVALUE_