Cache tag use cases

Purge content by topic

Cache tags are best used to purge aggregated data sets or a collection of objects that are heavily interdependent. This is especially valuable in cases where tens of thousands of objects must be purged at the same time. Purging with cache tags dramatically simplifies and improves efficiency of content management at the origin and on the edge.

As an example, consider a soccer website that displays live scores for its audiences. This website has multiple stats for live game scores, individual player stats, live league tables, leaderboards for goal scorers, and other aggregated player and team stats for a variety of attributes. Typically, every relevant play will require purging of multiple objects that need to be individually selected. With different teams playing in different tournaments and leagues simultaneously, purging these objects gets more and more complex. Cache tags allow you to assign tags to these objects for better manageability. You can now tag an object with team names or tournament names to purge everything related to these simultaneously without getting into the more granular complexities.

Purge static content on the fly

Cache tag headers are typically set at the origin, which means that you have less flexibility of your content. With tag purging, there are many interesting use cases for static objects. For example, you can control all images uploaded by user X and all images linked to product Y.

In this example, a website has 240.000 different images, each with multiple variants. The URL/filename pattern for the image (ID 122978) is as follows:







Use these steps to set up a cache tag for the example above, which will also work for any images with a similar naming scheme. You'll create a variable PMUSER_CT_PRODIMG, use a regex to extract the first five digits of the image name into PMUSER_CT_PRODIMG and assign a name for the cache tag as products-img-{{user.PMUSER_CT_PRODIMG}}. The tag name will be added to the above images with a value of products-img-122978. With this cache tag, you can purge all image variants.

How to

  1. Go to > CDN > Properties.

  2. Locate the property where you're adding the cache tag.

  3. Create a variable named PMUSER_CT_PRODIMG to store the calculated cache tag.

  4. Add the Set Variable behavior to the property configuration.

  5. Enter the following values, then click Save. For more information, see variable support.

    a. Create Value From: Expression

    b. Expression (variable support): {{builtin.AK_FILENAME}} (see built-in variables)

    c. Operation: Substitute

    d. Regex: ^(\d*)-.

    e. Replacement: $1

  6. Add the Cache Tag behavior to the property configuration.

  7. In the Tag Name field, enter products-img-{{user.PMUSER_CT_PRODIMG}}, then click Save. For more information, see behaviors that support variables.

Purge directory structures

Cache tags can also be used to purge entire directories by assigning a single tag to all objects within the directory structure.

For example, if you want to purge all objects within at the same time, you can set response headers for all objects within that directory to have the same tag. This tag can then be used to purge the entire directory structure under through a single request. This is particularly useful for streaming content.

Use cache tag nomenclature

Cache tags are scoped at an account level. If you have multiple groups using functionality within your account or you're testing on multiple local environments, follow some kind of nomenclature that helps distinguish tags created by these different groups.

This will primarily benefit in preventing cache tag collisions such as a scenario where multiple groups create the same tag and purge the content of others.

For example, consider an online apparel store that sells both clothes and shoes through two different departments, both of which fall within the same ​Akamai​ account. Assume both departments run a promo and tag some of their content as SALE. Now if the clothing department decides to purge all content tagged as SALE, this will also purge content tagged by the shoes department.

To avoid this scenario, use a nomenclature within departments. This could be as simple as starting each tag with <DepartmentName>. So in this case, to prevent any tag collision, there are two different tags, one for CLOTHES_SALEand the other for SHOES_SALE.

Similarly, you may want to test purging content on different local origins. We've seen power users leverage tag appending mechanisms on their end. For example, an object to be tagged with SALEcan now have multiple tags associated with it such as DEV_SALE, TEST_SALE, PROD_SALE. The relevant tags can be purged in the relevant environments.

Use multiple tag association

Plan for purge all or equivalent one-time emergency situations.

For example, imagine that a security vulnerability requires you to purge content across the board or across certain huge sets of content. Since there are no restrictions on the number of tags associated with an object, you can have a tag such as ALL_CONTENTor a small number of tags themed ALL_APP1_CONTENTto account for these rare but critical scenarios. Even though these tags can be associated with millions of objects, you'll only need to purge one tag when these situations arise.

Get validation error updates

Use the akamai-x-get-cache-tags pragma header to detect validation errors.

With cache tag purging, the Edge-Cache-Tag header is sent as a forward request response. When the forward response is received, the header is validated. If a validation error is detected, the header is re-written to remove all the problematic tags. In this case, the error is returned in a new X-Akamai-Cache-Tag-Error header, which is added to the response. If the header isn't there, then the tags are valid.

These are the possible validation mnemonics that may be returned:

  • Tag too long: TAG2BIG
  • Tag contains illegal char: BADCHAR
  • Too many tags: TAGSCNT
  • Too long header: HDR2BIG

Did this page help you?