Configure Image Processor on an application

Turn on Image Processor and create a Rules Engine rule that optimizes and caches images by the ims query string, from Console, API v4, or API v3.

Last updated

View as Markdown Agent setup

You configure Image Processor on an application from Azion Console, the Azion API v4, or the Azion API v3. For a first look at the product, refer to the Image Processor quickstart.

Prerequisites

Configure through Azion Console

To turn on Image Processor and Application Accelerator:

Open the application

Access Azion Console > Applications > your application.

Go to Main Settings > Modules > Default Modules
Turn on Image Processor
Turn on Application Accelerator
Select Save

The application runs with both modules. Application Accelerator is required to vary the cache on the ims query string, because the Cache vary by Query String control sits in the cache setting’s Application Accelerator section. It is not required to process an image.

To create the cache setting that gives the derived images a time-to-live (TTL) and varies the cache key by ims:

Open the Cache Settings tab

Access Azion Console > Applications > your application, then go to the Cache Settings tab.

Select + Cache
Name the cache setting

In Name, enter a name that identifies the setting. For example: Images.

Override the browser cache

Under Browser Cache, select Override cache settings.

Set how long the browser keeps the image

Set Max Age under Browser Cache to the duration the browser keeps the image.

Override the cache behavior

Under Cache, select Override cache behavior.

Set how long the derived image stays cached

Set Max Age under Cache to a long duration. Images change less often than other content, so a long duration reduces requests to the origin. Refer to Cache Settings for the maximum you can set.

Set the query string behavior

Under Application Accelerator, open Cache vary by Query String and set Behavior to Allowlist.

Add the ims field

In Fields, enter ims.

Turn on Sort

Turn on Sort to keep the cache key consistent regardless of the order the query string parameters arrive in.

Select Save

The cache setting appears in the Cache Settings tab, with a long TTL and the cache key varying by the ims field.

To create the rule that applies the cache setting and optimizes images:

Go to the Rules Engine tab
Select + Rule
Name the rule

Enter a name for the rule. For example: Optimize images.

Select Request Phase
Select the variable in the Criteria section

In the Criteria section, select the ${request_uri} variable.

Select matches as the comparison operator
Enter the argument

Enter \.(jpg|jpeg|gif|bmp|png|ico|webp|avif) as the argument.

In the Behaviors section, select Set Cache Policy
Select the cache setting you created
Select + Add Behavior
Add the Optimize Images behavior
Select Save

Optional — To convert images to WEBP or AVIF format, add the Add Request Header behavior and set its value to Accept: image/webp or Accept: image/avif.

Requests whose URI matches the argument carry the cache setting and run through Image Processor. To confirm that an image is optimized, inspect the page with your browser’s developer tools and find the request for the image. The query string carries ims=<width>x<height>, the resolution requested; remove the query string to load the original file.

Configure through the Azion API v4

To turn on Image Processor and Application Accelerator, send a PATCH request, replacing [TOKEN VALUE] with your personal token and <application_id> with your application ID:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/applications/<application_id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "modules": {
08 "application_accelerator": {
09 "enabled": true
10 },
11 "image_processor": {
12 "enabled": true
13 }
14 },
15 "active": true
16}

Read back, the application carries the following modules:

JSON
01{
02 "modules": {
03 "application_accelerator": { "enabled": true },
04 "cache": { "enabled": true },
05 "functions": { "enabled": true },
06 "image_processor": { "enabled": true }
07 }
08}

Application Accelerator is required to vary the cache on the ims query string, because that field belongs to modules.application_accelerator in a cache setting. It is not required to process an image.

To create the cache setting that gives the derived images a time-to-live (TTL) and varies the cache key by ims, send a POST request:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/cache_settings \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "Images",
08 "browser_cache": {
09 "behavior": "override",
10 "max_age": <browser_ttl_in_seconds>
11 },
12 "modules": {
13 "cache": {
14 "behavior": "override",
15 "max_age": <edge_ttl_in_seconds>
16 },
17 "application_accelerator": {
18 "cache_vary_by_querystring": {
19 "behavior": "allowlist",
20 "fields": ["ims"],
21 "sort_enabled": true
22 }
23 }
24 }
25}

For every field a cache setting carries, refer to Cache Settings.

The response returns the cache setting Azion created:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": <cache_setting_id>,
05 "name": "Images",
06 "browser_cache": {
07 "behavior": "override",
08 "max_age": <browser_ttl_in_seconds>
09 },
10 "modules": {
11 "cache": {
12 "behavior": "override",
13 "max_age": <edge_ttl_in_seconds>,
14 "stale_cache": { "enabled": false },
15 "large_file_cache": { "enabled": false, "offset": 1024 },
16 "tiered_cache": { "enabled": false }
17 },
18 "application_accelerator": {
19 "cache_vary_by_querystring": {
20 "behavior": "allowlist",
21 "fields": ["ims"],
22 "sort_enabled": true
23 },
24 "cache_vary_by_cookies": { "behavior": "ignore", "cookie_names": [] },
25 "cache_vary_by_devices": { "behavior": "ignore", "device_group": [] },
26 "cache_vary_by_method": []
27 }
28 }
29 }
30}

Copy the id value. To create the rule that applies the cache setting and optimizes images, replacing <cache_setting_id> with the ID you copied, send a POST request:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/request_rules \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "Optimize images",
08 "description": "Apply the cache setting and optimize images",
09 "active": true,
10 "criteria": [
11 [
12 {
13 "variable": "${request_uri}",
14 "operator": "matches",
15 "conditional": "if",
16 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
17 }
18 ]
19 ],
20 "behaviors": [
21 {
22 "type": "set_cache_policy",
23 "attributes": { "value": <cache_setting_id> }
24 },
25 {
26 "type": "optimize_images"
27 }
28 ]
29 }

The response echoes the criteria and behaviors Azion accepted:

JSON
01{
02 "data": {
03 "criteria": [
04 [
05 {
06 "variable": "${request_uri}",
07 "operator": "matches",
08 "conditional": "if",
09 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
10 }
11 ]
12 ],
13 "behaviors": [
14 {
15 "type": "set_cache_policy",
16 "attributes": { "value": <cache_setting_id> }
17 },
18 {
19 "type": "optimize_images"
20 }
21 ]
22 }
23}

Optional — To convert images to WEBP or AVIF format, add a behavior of type add_request_header with "attributes": {"value": "Accept: image/webp"} or "attributes": {"value": "Accept: image/avif"}.

Requests whose URI matches the argument carry the cache setting and run through Image Processor. To confirm that an image is optimized, inspect the page with your browser’s developer tools and find the request for the image. The query string carries ims=<width>x<height>, the resolution requested; remove the query string to load the original file.

Configure through the Azion API v3

To turn on Image Processor and Application Accelerator, send a PATCH request, replacing [TOKEN VALUE] with your personal token and <application_id> with your application ID:

Shell
01curl --location --request PATCH 'https://api.azionapi.net/edge_applications/<application_id>' \
02--header 'Accept: application/json; version=3' \
03--header 'Content-Type: application/json' \
04--header 'Authorization: Token [TOKEN VALUE]' \
05--data {
06 "application_acceleration": true,
07 "image_optimization": true
08}

The response returns the updated value.

Application Accelerator is required to vary the cache on the ims query string. It is not required to process an image.

To create the cache setting that gives the derived images a time-to-live (TTL) and varies the cache key by ims, send a POST request:

Shell
01curl --location 'https://api.azionapi.net/edge_applications/<application_id>/cache_settings' \
02--header 'Accept: application/json; version=3' \
03--header 'Content-Type: application/json' \
04--header 'Authorization: Token [TOKEN VALUE]' \
05--data {
06 "name": "QS15D img",
07 "browser_cache_settings": "override",
08 "browser_cache_settings_maximum_ttl": <browser_ttl_in_seconds>,
09 "cdn_cache_settings": "override",
10 "cdn_cache_settings_maximum_ttl": <edge_ttl_in_seconds>,
11 "cache_by_query_string": "whitelist",
12 "query_string_fields": [
13 "ims"
14 ]
15}

For every field a cache setting carries, refer to Cache Settings.

The response returns the cache setting Azion created:

JSON
01{
02 "results": {
03 "id": <cache_setting_id>,
04 "name": "QS15D img",
05 "browser_cache_settings": "override",
06 "browser_cache_settings_maximum_ttl": <browser_ttl_in_seconds>,
07 "cdn_cache_settings": "override",
08 "cdn_cache_settings_maximum_ttl": <edge_ttl_in_seconds>,
09 "cache_by_query_string": "whitelist",
10 "query_string_fields": [
11 "ims"
12 ],
13 "enable_query_string_sort": false,
14 "cache_by_cookies": "ignore",
15 "cookie_names": null,
16 "adaptive_delivery_action": "ignore",
17 "device_group": [],
18 "enable_caching_for_post": false,
19 "l2_caching_enabled": false,
20 "is_slice_configuration_enabled": false,
21 "is_slice_edge_caching_enabled": false,
22 "is_slice_l2_caching_enabled": false,
23 "slice_configuration_range": 1024,
24 "enable_caching_for_options": false,
25 "enable_stale_cache": true,
26 "l2_region": null
27 }
28}

Copy the id value. To create the rule that applies the cache setting and optimizes images, replacing <cache_setting_id> with the ID you copied, send a POST request:

Shell
01curl --location --globoff 'https://api.azionapi.net/edge_applications/<application_id>/rules_engine/request/rules' \
02--header 'Accept: application/json; version=3' \
03--header 'Authorization: Token [TOKEN VALUE]' \
04--header 'Content-Type: application/json' \
05--data {
06 "name": "ImgProcessor",
07 "behaviors": [
08 {
09 "name": "set_cache_policy",
10 "target": "<cache_setting_id>"
11 },
12 {
13 "name": "optimize_images",
14 "target": null
15 }
16 ],
17 "criteria": [
18 [
19 {
20 "variable": "${request_uri}",
21 "operator": "matches",
22 "conditional": "if",
23 "input_value": "\\.(jpg|jpeg|gif|bmp|png)"
24 },
25 {
26 "variable": "${uri}",
27 "operator": "matches",
28 "conditional": "or",
29 "input_value": "\\.(jpg|jpeg|gif|bmp|png)$"
30 }
31 ]
32 ]
33}

The response returns the rule Azion created:

JSON
01{
02 "results": {
03 "id": <rule_id>,
04 "name": "ImgProcessor",
05 "phase": "request",
06 "behaviors": [
07 {
08 "name": "set_cache_policy",
09 "target": "132186"
10 },
11 {
12 "name": "optimize_images",
13 "target": null
14 }
15 ],
16 "criteria": [
17 [
18 {
19 "variable": "${request_uri}",
20 "operator": "matches",
21 "conditional": "if",
22 "input_value": "\\.(jpg|jpeg|gif|bmp|png)"
23 },
24 {
25 "variable": "${uri}",
26 "operator": "matches",
27 "conditional": "or",
28 "input_value": "\\.(jpg|jpeg|gif|bmp|png)$"
29 }
30 ]
31 ],
32 "is_active": true,
33 "order": 3,
34 "description": null
35 }
36}

Requests whose URI matches either argument carry the cache setting and run through Image Processor. To confirm that an image is optimized, inspect the page with your browser’s developer tools and find the request for the image. The query string carries ims=<width>x<height>, the resolution requested; remove the query string to load the original file.

Next steps