Azion CLI cache-setting

Azion CLI commands that create, list, describe, update, and delete cache settings, with every flag, its type, and its default.

Last updated

View as Markdown Agent setup

The Azion CLI cache-setting commands create, list, describe, update, and delete the cache settings of an application, the objects that tell the browser and Azion’s cache how long to keep a response. Each command takes the --application-id of the application that holds the setting. The values each flag accepts, and the field each one writes, are on the cache settings page. The options every command accepts, such as --format, --out, and -y, are on Global options.

Create

azion create cache-setting creates a cache setting in an application with the name and values you pass:

azion create cache-setting [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that holds the cache setting.
--browser-cache-behavior—string"honor"How the browser caches the content, such as honor or override.
--browser-cache-max-age—int—Time, in seconds, that the browser keeps the content before it expires.
--cache-by-cookies—string"ignore"Whether cookies vary the cached content.
--cache-by-query-string—string"ignore"How the query string variations of a URL vary the cached content.
--cookie-names—strings—Names of the cookies whose name and value distinguish cached objects.
--enable-caching-for-options—string"false"Turns caching of OPTIONS requests on (true) or off (false).
--enable-caching-for-post—string—Turns caching of POST requests on (true) or off (false).
--file—string—Path to a JSON file with the attributes of the cache setting. Use - to read the JSON from standard input.
--name—string—Name of the cache setting.
--query-string-fields—strings—Query string parameters that split the cache of the same URL.
--tiered-caching-enabled—string—Turns Tiered Cache on (true) or off (false) for the cache setting.

--enable-caching-for-post true requires Application Accelerator on the application. Without it, the command fails with this error:

Error: Failed to create the Cache Settings configuration: ["To use this value, you must first enable the Application Accelerator module in Edge Application's Main Settings."]. Check your settings and try again. If the error persists, contact Azion support.

This command creates a cache setting named my-cache in the application with ID 1234567890, and sets the browser to keep the content for one hour:

azion create cache-setting --application-id 1234567890 --name my-cache --browser-cache-behavior override --browser-cache-max-age 3600

The command prints the ID of the cache setting:

Created Cache Settings configuration with ID 123466

List

azion list cache-setting lists the cache settings of one application, 50 to a page:

azion list cache-setting [flags]
FlagShortTypeDefaultDescription
--application-id—int—Required. ID of the application whose cache settings to list. Without it, the command asks for the ID.
--details———Replaces the BROWSER CACHE SETTINGS column with the BROWSER CACHE and CACHE columns.
--filter—string—Name to filter the list by.
--order-by—string—Field to sort the list by.
--page—int1Number of the page to return.
--page-size—int50Number of cache settings on each page.

This command lists the cache settings of the application with ID 1234567890, with the browser cache and the cache behavior of each:

azion list cache-setting --application-id 1234567890 --details

The command prints one row per cache setting:

Text
01ID NAME BROWSER CACHE CACHE
02123466 my-cache override honor
03123467 my-cache-file honor override

Describe

azion describe cache-setting prints the values of one cache setting:

azion describe cache-setting [flags]
FlagShortTypeDefaultDescription
--application-id—int—Required. ID of the application that holds the cache setting.
--cache-setting-id—int—Required. ID of the cache setting to describe.

This command describes the cache setting with ID 123466:

azion describe cache-setting --application-id 1234567890 --cache-setting-id 123466

The command prints the ID, the name, the browser cache, and the cache values of the setting:

Text
01ID: 123466
02Name: my-cache
03Browser Cache Settings: {"behavior":"override","max_age":3600}
04Modules: {"application_accelerator":{"cache_vary_by_cookies":{"behavior":"ignore","cookie_names":[]},"cache_vary_by_devices":{"behavior":"ignore","device_group":[]},"cache_vary_by_method":[],"cache_vary_by_querystring":{"behavior":"ignore","fields":[],"sort_enabled":false}},"cache":{"behavior":"honor","large_file_cache":{"enabled":false,"offset":1024},"max_age":60,"stale_cache":{"enabled":false},"tiered_cache":{"enabled":false}}}

With --format json, the command prints the full object: browser_cache, created_at, id, modules, and name. The modules object holds application_accelerator, with the cache variation by cookies, devices, method, and query string, and cache, with the cache behavior, max_age, large_file_cache, stale_cache, and tiered_cache.

Update

azion update cache-setting changes the name or the values of a cache setting:

azion update cache-setting [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that holds the cache setting.
--browser-cache-max-age—int—Time, in seconds, that the browser keeps the content before it expires.
--browser-cache-settings—string"honor"How the browser caches the content. On create, the same value is --browser-cache-behavior.
--cache-by-cookies—string"ignore"Whether cookies vary the cached content.
--cache-by-query-string—string"ignore"How the query string variations of a URL vary the cached content.
--cache-setting-id—int—ID of the cache setting to update.
--cookie-names—strings—Names of the cookies whose name and value distinguish cached objects.
--enable-caching-for-options—string"false"Turns caching of OPTIONS requests on (true) or off (false).
--enable-caching-for-post—string—Turns caching of POST requests on (true) or off (false).
--enable-caching-string-sort—string—Turns query string sorting on (true) or off (false) for the cache.
--file—string—Path to a JSON file with the attributes to change. Use - to read the JSON from standard input.
--name—string—New name of the cache setting.
--query-string-fields—strings—Query string parameters that split the cache of the same URL.

To change the browser cache of a setting, use --file, as in Use a JSON file.

This command renames the cache setting with ID 123466 to my-cache-renamed:

azion update cache-setting --application-id 1234567890 --cache-setting-id 123466 --name my-cache-renamed

The command prints the ID of the updated cache setting:

Updated a Cache Settings configuration with ID 123466

Delete

azion delete cache-setting deletes a cache setting from an application:

azion delete cache-setting [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that holds the cache setting.
--cache-setting-id—int—ID of the cache setting to delete.

This command deletes the cache setting with ID 123467:

azion delete cache-setting --application-id 1234567890 --cache-setting-id 123467 -y

The command confirms the deletion:

Caches settings configuration 123467 was successfully deleted

Use a JSON file

azion create cache-setting and azion update cache-setting read the attributes of the cache setting from a JSON file with --file. The file takes the fields that no flag sets, such as the cache behavior and max_age under modules.cache.

This file creates a cache setting named my-cache-file. The browser follows the cache headers of the origin, and Azion’s cache keeps the content for 600 seconds:

JSON
01{
02 "name": "my-cache-file",
03 "browser_cache": {
04 "behavior": "honor",
05 "max_age": 0
06 },
07 "modules": {
08 "cache": {
09 "behavior": "override",
10 "max_age": 600
11 }
12 }
13}

Pass the file and the application ID to the create command:

azion create cache-setting --application-id 1234567890 --file cache-create.json

The command prints the ID of the cache setting:

Created Cache Settings configuration with ID 123467

On update, the file carries only the fields to change, and the fields it leaves out keep their values. This file renames the cache setting and sets the browser to keep the content for 300 seconds:

JSON
01{
02 "name": "my-cache-file-updated",
03 "browser_cache": {
04 "behavior": "override",
05 "max_age": 300
06 }
07}

Pass the file with the application ID and the cache setting ID to the update command:

azion update cache-setting --application-id 1234567890 --cache-setting-id 123467 --file cache-update.json

The command prints the ID of the updated cache setting:

Updated a Cache Settings configuration with ID 123467

After this update, modules.cache still holds the override behavior and the max_age of 600 that the create file set.

Global options

The options every command accepts, such as --format, --out, and -y.

Cache settings

Every field of a cache setting, the values it accepts, and the errors the API returns.

Azion CLI application

The commands that create and manage the application that holds the cache settings.

Azion CLI rules-engine

The commands that create the rules that apply a cache setting to requests.