Real-Time Purge
Look up every purge type of Real-Time Purge: URL, cache key, and wildcard arguments, the two layers, the API body, errors, and limits.
Real-Time Purge is a Platform Resource that removes a cached object from Cache, or from Tiered Cache, before its time to live (TTL) ends. Once the object is in neither Cache nor Tiered Cache, the next request for it fetches the current version from the origin. Use a purge to serve an update the origin already has, to remove an obsolete object, or to keep control of what Azion serves for dynamic content.
A purge takes one of three arguments: a list of URLs, a list of cache keys, or one wildcard expression. Azion confirms each purge, queues it, and lists it in the purge history when it is complete. For the steps, refer to Purge cached content. For the format of a key, refer to Cache keys.
Interfaces
Five interfaces send the same purge. Each one names the purge type and carries the argument list. Every interface except Azion Lib also names the layer, and Azion Lib purges the Cache layer.
| Interface | Purge |
|---|---|
| Azion Console | Real-Time Purge > Purge opens Create Real-Time Purge, with Layer Settings, Purge Type, and Arguments List, one argument per line |
| Azion API v4 | POST /v4/workspace/purge/{purge_type}, with purge_type set to url, cachekey, or wildcard, and a body with items and layer |
| Azion CLI | azion purge with --urls, --cachekey, or --wildcard, and --layer |
azion.config.js |
An entry of the purge array, of type AzionPurge, with type, items, and layer |
| Azion Lib | purgeURL, purgeCacheKey, and purgeWildCard from azion/purge |
The API authenticates with a personal token in the Authorization: Token <token> header. For more information, refer to Personal tokens.
Layers
A purge names the layer it clears. The layer field of the API body and the --layer flag of the CLI are optional, and both default to cache.
| Layer | API value | What it purges |
|---|---|---|
| Cache | cache, the default |
The objects cached on Azion’s distributed infrastructure |
| Tiered Cache | tiered_cache |
The objects in the second cache layer, on Applications whose cache settings turn Tiered Cache on; by cache key only |
A URL or wildcard purge with the tiered_cache layer returns error 30001. To purge an object from both layers, purge Tiered Cache first and then Cache. In that order, the cache is not refilled from a stale Tiered Cache copy.
Purge types
The purge_type segment of the API path, the CLI flag, and the Console’s purge type name the same three types.
| Type | purge_type |
Argument | Per request | Layers |
|---|---|---|---|---|
| URL | url |
A list of URLs | Up to 50 | cache |
| Cache key | cachekey |
A list of cache keys | Up to 50 | cache, tiered_cache |
| Wildcard | wildcard |
One wildcard expression | 1 | cache |
URL purge
A URL purge takes a list of URLs and is not recursive: only the URLs in the list leave the cache. Azion converts each URL to its cache key with no content variation. So a variation by cookie, device group, image format, or request body does not expire with it. Purge those variations with a cache key or a wildcard.
A variation by query string is part of the URL, so it expires when the arguments are in the same order as in the cache key. With sort_enabled on in the cache setting, send the arguments in alphabetical order, or use a cache key or wildcard purge. For the sort_enabled field, refer to Cache settings.
A URL is scheme://host or host, with an optional /path and ?query-string. Without a scheme, Azion purges both the HTTP and the HTTPS copies. An asterisk (*) in a URL purge is a literal character, not a wildcard. The list below carries four valid URL arguments:
http://www.example.comhttp://static.example.com/include/site.csshttps://static.example.com/include/site.jsdynamic.example.com/app.py?argument
Cache key purge
A cache key purge takes a list of cache keys. A key names one variation of an object. With Advanced Cache Key, a Feature of Application Accelerator, a key can vary by query string, sorted or not, and by cookie, device group, or request method. Through Image Processor, a key can also vary by image format. To purge every variation of an object, list every key. A cache key purge is the only type that reaches the Tiered Cache layer.
Wildcard purge
A wildcard purge takes one expression: scheme://host or host, with an optional /path and ?query-string. The expression carries an asterisk (*) in the path or in the query string. Several asterisks match a more complex path. Each request carries one expression, and a wildcard purge reaches the Cache layer only, not Tiered Cache. The list below carries ten valid wildcard expressions:
www.example.com/*static.example.com/include/*.cssstatic.example.com/*/site.jsstatic.example.com/static/images/image_1.jpg?ims=*www.example.com/alpha*www.example.com/*beta*www.example.com/*a*/charliewww.example.com/*a*/*a*www.example.com/*?b*www.example.com/*?*2*c=*
Purge content that varies
When a cache setting varies the cache key, one object has one key per variation. The table names the purge that reaches each kind of variation.
| Variation | How to purge |
|---|---|
| Cookies | A cache key purge that lists every variation, or a wildcard purge with @@* at the end |
| Query string | A cache key purge that lists every variation, a wildcard purge with ?* at the end, or a URL purge that names only the arguments in the key, in alphabetical order when sort_enabled is on |
| Device group | A cache key purge that lists every variation, or a wildcard purge with @@* at the end |
| Image Processor | A cache key purge that lists every variation, or a wildcard purge with * at the end |
| Large File Optimization | A cache key purge that lists every fragment’s key, or a wildcard purge such as static.example.com/media/file.mp4* |
Cached POST and OPTIONS |
A cache key purge that lists every variation, or a wildcard purge with @@* at the end |
Query-string, cookie, device group, and request method variation come from Advanced Cache Key, in Application Accelerator. Application Accelerator also caches POST and OPTIONS responses; without it, Azion caches GET and HEAD only. For the behaviors, refer to Application Accelerator settings.
An image that Image Processor serves has one key per processing and per format when the cache setting names ims in its query-string allowlist. When the cache setting does not vary the key by query string, the ims value is not part of the key, so every size and processing of the path shares a key, and the first one stored answers every ims value. With ims in the allowlist, the key carries the host and path, then @@, the ims query string, and the converted format at the end, with no separator. The four keys below belong to one image:
httpstatic.example.com/static/images/image.jpg@@httpstatic.example.com/static/images/image.jpg@@webphttpstatic.example.com/static/images/image.jpg@@?ims=88xhttpstatic.example.com/static/images/image.jpg@@?ims=88xwebp
With Large File Optimization on in the cache setting, Azion caches a large object in fragments, each with its own key. The file can stay in the cache after a purge of its URL. To purge it, list each fragment’s key, or use the wildcard static.example.com/media/file.mp4*. That wildcard clears every fragment of one file.
Request body
The API reads the purge type from the path and the arguments from items. The request body below sends a URL purge through POST /v4/workspace/purge/url:
A wildcard purge goes through POST /v4/workspace/purge/wildcard; without layer, the API purges cache:
A cache key purge goes through POST /v4/workspace/purge/cachekey:
Each request answers with HTTP 201, state set to executed, and the items and the layer under data:
The CLI sends the same three purges from the command line, the last one to the Tiered Cache layer:
Each command prints one line:
Once a purge of the Cache layer completes, a request for the object sent with Pragma: azion-debug-cache returns x-cache: MISS, because that layer no longer holds the object.
Purge queue and history
After you create a purge, a message confirms the creation. Azion then queues the purge. The purge appears in the purge history when it is complete, because the result takes time to propagate across Azion’s distributed infrastructure. In Azion Console, the Real-Time Purge list shows each purge with its Date, User, Layer, Type, and Arguments, and the Repurge action sends the same purge again.
Errors
The API answers each request below with HTTP 400. The body carries the code, the title, and a detail.
| Code | Title | Cause | Detail | What to do |
|---|---|---|---|---|
30001 |
Invalid Purge Layer For Purge Type |
layer is tiered_cache on a url or wildcard purge. |
Invalid purge layer for purge type "url". |
Purge Tiered Cache by cache key, or set layer to cache. |
30003 |
Unauthorized Domain |
An item names a domain the account does not own. | The domain is not authorized for your account. |
Correct the domain in the item. A purge reaches only the domains the account owns. |
30005 |
Invalid Purge Cachekey |
An item of a cachekey purge is not a valid cache key. |
The Content must be a valid cachekey. |
Send the key as the x-cache-key header shows it; the format is on Cache keys. |
10065 |
List Field Max Length |
items has more than 50 elements on a url or cachekey purge, or more than 1 on a wildcard purge. |
Ensure this field has no more than 50 elements.; on a wildcard purge, Ensure this field has no more than 1 elements., with meta.max_length set to 1 |
Split the list into requests of 50 items or fewer, and send one wildcard expression per request. |
Limits
The bounds below apply to purge requests. Each row names the API’s answer past the value.
| Value | Bound | Past the bound |
|---|---|---|
| URL or cache key length | 4,096 characters | The API accepts a longer URL when it receives the request: a purge of one 4,098-character URL returns HTTP 201. |
| URL and cache key objects per request | 50 objects | HTTP 400, error 10065 |
| Wildcard expressions per request | 1 | HTTP 400, error 10065 |
Six more bounds set the rate of purge requests, the length of a wildcard, and how much purge history Azion keeps.
| Value | Bound |
|---|---|
| URL and cache key requests per client | 200 requests |
| URL and cache key objects per minute | 10,000 objects every 60 seconds |
| Wildcard requests per day | 2,000 requests in a 24-hour interval |
| Wildcard expression length | 256 characters |
| Purge history | 1,000,000 requests |
| Purge history retention | 6 months |
Azion pricing lists the purges each plan includes.