Rules Engine for Applications
Look up every criterion variable, operator, and behavior a rule of an Application can use, by phase, and the Platform Resource each one requires.
Rules Engine for Applications is a Feature of Applications that holds the rules of an Application. A rule is conditional logic that the Application applies to a request or to its response. For example, a rule can send the request to a Connector, apply a cache setting, or invoke a Function Instance. Each rule has criteria, its if, and behaviors, its then. It runs its behaviors only when a request matches its criteria. Every rule belongs to one phase: the Request Phase acts on the request, and the Response Phase acts on the response.
Some variables and behaviors need a Platform Resource turned on in the Application, and each table on this page names it. For the order in which an Application runs its rules and behaviors, refer to How Applications works.
When the deployment of a Workload sets both the Application and a Firewall, the Firewall decides earlier whether the request reaches the Application at all. For its rules, refer to Rules Engine for Firewall.
Rule fields
A new Application has no rules, and Create request and response rules shows how to create one in Azion Console. In the API, a rule is a JSON object: a request sets five of its fields, and the platform sets and returns the other five. For the fields you set, the Description column also names the label of each one in the rule form of Azion Console.
| Field | Type | Required | Description |
|---|---|---|---|
id |
integer | Read-only | The identifier every later call on the rule uses |
name |
string, 1 to 250 characters | Yes | The name the rule list shows, rendered as Name in General |
description |
string, up to 1,000 characters | No | A comment the rule list shows, rendered as Description in General. Defaults to an empty string |
active |
boolean | No | Whether the rule runs, the Active switch in Status. Defaults to true |
criteria |
array of 1 to 5 groups, each an array of 1 to 10 criteria | Yes | The conditions a request must meet. Criteria lists every variable and operator |
behaviors |
array of 1 to 10 behavior objects | Yes | What the rule does when the request matches. Behaviors lists every one |
order |
integer, 0 to 199 | Read-only | The position of the rule in the list of its phase |
last_editor |
string | Read-only | The account that last changed the rule |
last_modified |
date-time | Read-only | When the rule last changed |
created_at |
date-time | Read-only | When the rule was created |
The Console rule list does not show id, and azion list rules-engine prints it as ID. Give each rule a unique name. Past 1,000 characters of description, the Console shows Description should not exceed 1000 characters.
The platform assigns order as rules are created: the first rule of a phase carries 0, and the next one carries 1. The Console numbers the same positions from 1, so the rule whose order is 0 is the one its list shows as 1. The Console rule list lets you move a rule, and a position past the end of the list places the rule last. The API reorders a phase with one call, which the API section lists.
Phases
You set the phase of a rule when you create it, and you cannot change it later. To run the same logic in the other phase, create a new rule there. In Azion Console, the rule list groups the rules by phase, and the API keeps each phase in its own collection.
| Phase | What its rules act on | API collection |
|---|---|---|
| Request Phase | The request the user sends to the Application | /v4/workspace/applications/<application-id>/request_rules |
| Response Phase | The response the Application delivers to the user | /v4/workspace/applications/<application-id>/response_rules |
Each phase offers its own set of variables and behaviors. A value that exists only once the origin or a Function answers, such as ${status}, is readable only in the Response Phase. The Phases column of the variable table and the two API columns of the behavior table say which phase accepts each one.
Criteria
A criterion is a condition a request must meet: a variable, an operator, and, for most operators, an argument to compare the variable with. In the API, a criterion is an object with four keys: variable, operator, conditional, and argument.
This criterion matches a request from a desktop browser, with a regular expression on the User-Agent header:
Variables
A variable is a value of the request or of the response, written ${name}. The Phases column names where a criterion can read it. ${request_uri} and ${device_group} require Application Accelerator turned on in the Application. A rule that reads one of them in an Application with Application Accelerator off is refused. The API answers HTTP 400 with the error code 25047, Missing Required Modules, and the Errors section carries the full body. ${uri} needs no Platform Resource, so it is the URI variable for an Application without Application Accelerator.
Six rows name a pattern instead of a variable. In ${arg_name}, ${cookie_name}, ${http_name}, ${sent_http_name}, ${upstream_cookie_name}, and ${upstream_http_name}, replace name with the argument, cookie, or header to read.
| Variable | What it holds | Example | Phases |
|---|---|---|---|
${arg_name} |
The value of the query-string argument name. Replace each hyphen in name with an underscore |
${arg_search} holds test for /path?search=test |
Request, Response |
${args} |
Every argument name and value in the query string | ${args} holds search=test for /path?search=test |
Request, Response |
${cookie_name} |
The value of the cookie name. Replace each hyphen in name with an underscore |
${cookie_icl_current_language} holds pt-br for icl_current_language = pt-br |
Request, Response |
${device_group} |
The name of the device group the request matches, among the device groups of the Application. Requires Application Accelerator | Mobile |
Request, Response |
${domain} |
The host name or Host header of the request, as ${host} reads it, without the last subdomain after the second-level domain |
blog.domain.com for az.blog.domain.com |
Request, Response |
${geoip_city} |
The city name | Frankfurt am Main |
Request, Response |
${geoip_city_continent_code} |
The two-letter continent code | EU, for Europe |
Request, Response |
${geoip_city_country_code} |
The two-letter country code | IN, for India |
Request, Response |
${geoip_city_country_name} |
The country name | United States |
Request, Response |
${geoip_continent_code} |
The two-letter continent code | NA, for North America |
Request, Response |
${geoip_country_code} |
The two-letter country code | RU, for Russia |
Request, Response |
${geoip_country_name} |
The country name | France |
Request, Response |
${geoip_region} |
The two-letter region code | FL, for Florida |
Request, Response |
${geoip_region_name} |
The region name | Ontario |
Request, Response |
${host} |
In order of precedence: the host name in the request line, the value of the Host header, or the name of the server that serves the request |
blog.domain.com |
Request, Response |
${http_name} |
The value of the request header name. Write name in lowercase and replace each hyphen with an underscore. name must be a valid HTTP request header |
${http_accept} holds image/webp,image/apng for Accept: image/webp,image/apng |
Request, Response |
${remote_addr} |
The IP address of the client that sends the request | 200.10.2.50 |
Request, Response |
${remote_port} |
The TCP source port of the client connection, which changes from one connection to the next | 6742 |
Request, Response |
${remote_user} |
The user name sent through basic authentication, when the request carries one | username |
Request, Response |
${request} |
The first line of the request as the client sent it: the method, the URI, and the HTTP version | GET /path HTTP/2.0 |
Request, Response |
${request_body} |
The content of the request body, without the request line or the headers | {"name": "azion", "action": "login"} |
Request, Response |
${request_method} |
The HTTP method of the request | GET |
Request, Response |
${request_uri} |
The complete URI of the request, query string included, with special UTF-8 characters URL encoded. Requires Application Accelerator | /path?var=value%20of%20var |
Request, Response |
${scheme} |
The scheme of the request | https |
Request, Response |
${sent_http_name} |
The value of the response header name. Write name in lowercase and replace each hyphen with an underscore |
${sent_http_content_length} holds 9593 for Content-Length: 9593 |
Response |
${server_addr} |
The IP address of the server that receives the request | 200.0.0.0 |
Request |
${server_port} |
The port of the server that receives the request | 8080 |
Request |
${status} |
The status code of the response | 200 |
Response |
${tcpinfo_rtt} |
The round-trip time (RTT) of the client’s TCP connection, in microseconds | 24763 |
Response |
${upstream_addr} |
The IP address and port of the origin that answered. Several origins are separated by commas. After an internal redirect from one group of servers to another, started by an X-Accel-Redirect or an error page, the groups are separated by a colon |
192.168.1.1:80, 192.168.1.2:80, or 192.168.1.1:80, 192.168.1.2:80 : 192.168.10.1:80, 192.168.10.2:80 after a redirect |
Response |
${upstream_cookie_name} |
The value of the cookie name that the origin sends in Set-Cookie. When several origins answer one request, only the cookies of the last one are kept |
${upstream_cookie_uuid} holds 12345 for Set-Cookie: uuid = 12345 |
Response |
${upstream_http_name} |
The value of the header name that the origin sends. Write name in lowercase and replace each hyphen with an underscore. When several origins answer one request, only the headers of the last one are kept |
${upstream_http_server} holds UploadServer for Server: UploadServer |
Response |
${upstream_status} |
The status code the origin returns. Several origins are separated by commas, and the groups of an internal redirect by a colon, as in ${upstream_addr} |
200, 201, or 500, 502 : 200, 200 after a redirect |
Response |
${uri} |
The normalized, URL-decoded URI of the request. The value can change while the request is processed, for example after an internal redirect or when an index file answers. For the query string or URL-encoded characters, read ${request_uri} |
/path/my file.txt |
Request, Response |
Mutual Transport Layer Security (mTLS) variables
These variables hold the client certificate that a request presents over mTLS, where the client also authenticates with a certificate. A criterion reads them only in the Request Phase. For how a Workload asks for and validates client certificates, refer to mTLS.
| Variable | What it holds | Example |
|---|---|---|
${ssl_client_cert} |
The client certificate in Privacy-Enhanced Mail (PEM) format. Deprecated: read ${ssl_client_escaped_cert} instead |
-----BEGIN CERTIFICATE----- MIICnz... -----END CERTIFICATE----- |
${ssl_client_escaped_cert} |
The client certificate in PEM format, as a URL-encoded string | -----BEGIN%20CERTIFICATE-----%0AMIICnz...%0A-----END%20CERTIFICATE----- |
${ssl_client_fingerprint} |
The Secure Hash Algorithm 1 (SHA-1) fingerprint of the client certificate | 2fd4e1c67a2d28fced849 |
${ssl_client_i_dn} |
The issuer Distinguished Name (DN) string of the client certificate | /C=US/ST=California/L=San Francisco/O=Example CA/CN=issuer.com |
${ssl_client_s_dn} |
The subject DN string of the client certificate | /C=US/ST=California/L=San Francisco/O=Example CA/CN=example.com |
${ssl_client_s_dn_parsed} |
The subject Common Name (CN) extracted from the client certificate, as a string | example.com |
${ssl_client_serial} |
The serial number of the client certificate | 6C:0A:83:7E:92:3B:D6:C6:E3:56:50:E7 |
${ssl_client_v_end} |
The expiration date of the client certificate, in the format YYYYMMDDHHmmSS |
20230115120000 |
${ssl_client_v_remain} |
The number of days until the client certificate expires | 100 |
${ssl_client_v_start} |
The start date of the client certificate, in the format YYYYMMDDHHmmSS |
20230115120000 |
${ssl_client_verify} |
The result of the client certificate verification | SUCCESS, FAILED:reason, or NONE |
Most mTLS services expect to receive the client certificate itself. A Request Phase rule can send ${ssl_client_escaped_cert} to the origin with Add Request Header, in the X-Forward-Client-Cert (XFCC) header. The origin then reads the certificate data from that header.
Variables in behavior arguments
A behavior that takes an argument can read the variables of its phase. For example, a rule can write the device group or the geolocation of a request into a cookie or a header.
This Response Phase rule sets a cookie that records the host of the request:
| Variable | Operator | Argument | |
|---|---|---|---|
| If | ${host} |
is_equal |
host.com |
| Behavior | Argument | |
|---|---|---|
| Then | Add Response Cookie | cookie-host-value=${host} |
When the rule matches, the response carries Set-Cookie: cookie-host-value=host.com.
Two more variables act as functions: each takes an argument, and both work only inside a behavior argument.
| Variable | What it returns | Example |
|---|---|---|
${cookie_time_offset(number)} |
The current date plus an offset of number seconds, for the expiration of a cookie |
cookie-name=cookie-value; Expires=${cookie_time_offset(3600)} in Add Response Cookie makes the cookie expire 1 hour after it is created |
${encode_base64(string)} |
string, encoded in base64 |
${encode_base64(http://www.yourdomain.com/)} returns aHR0cDovL3d3dy55b3VyZG9tYWluLmNvbS8= |
Operators
A criterion compares its variable with its argument through an operator, and the API sends the operator as one of these values in operator.
| Operator | The criterion matches when | Argument |
|---|---|---|
is_equal |
The value is exactly the argument | String |
is_not_equal |
The value is not the argument | String |
starts_with |
The value starts with the argument | String |
does_not_start_with |
The value does not start with the argument | String |
matches |
The value matches the regular expression in the argument | Regular expression |
does_not_match |
The value does not match the regular expression in the argument | Regular expression |
exists |
The variable has a value, such as ${arg_search} with a search argument |
None |
does_not_exist |
The variable has no value, such as ${arg_search} without a search argument |
None |
Conditionals
Criteria combine inside groups, and a rule holds 1 to 5 groups of 1 to 10 criteria each. In a group, the first criterion carries the conditional if, and each later criterion carries and or or. In Azion Console, the rule form joins criteria with And and Or.
Inside a group, and takes precedence over or. To set the precedence yourself, split the conditions into groups. The groups of a rule are joined by and, so a request matches the rule only when it matches every group. For example, a rule that needs A or B, and also C, puts A or B in one group and C in a second one.
In the API, criteria is a list of groups, and each group is a list of criterion objects, as in [[{ … }]].
Behaviors
A behavior is an action a rule runs on a request, or on a response, that matches its criteria. A rule carries 1 to 10 behaviors. In Azion Console, the rule form labels the first behavior row Then and each later row And. Some behaviors cannot be added together, and the API refuses those combinations with HTTP 400:
- A behavior after a final one, such as Deliver, with
25010. - A behavior that a rule takes only once, such as Bypass Cache, repeated in the rule, with
25011. - Set Cache Policy beside Deny (403 Forbidden), Redirect To (301 Moved Permanently), Redirect To (302 Found), or No Content (204), with
25012.
In Azion Console, Add Behavior turns off once Deliver is in the rule.
In the API, each behavior is an object with a type. A behavior that takes an argument carries it in attributes.value, and Capture Match Groups carries three named attributes instead. The Console refuses some arguments that contain a space, with Argument cannot contain spaces, use %20 instead.
The two API columns give the type each phase accepts, and Requires names the Platform Resource that must be turned on in the Application. When that Platform Resource is off, Azion Console adds - Required Application Accelerator, - Required Image Processor, or - Required Function to the label. A new Application has Cache and Functions on, and Application Accelerator and Image Processor off.
| Behavior | API type, Request Phase |
API type, Response Phase |
Requires |
|---|---|---|---|
| Add Request Cookie / Add Response Cookie | add_request_cookie |
set_cookie |
Application Accelerator |
| Add Request Header / Add Response Header | add_request_header |
add_response_header |
None |
| Bypass Cache | bypass_cache |
Not available | Application Accelerator |
| Capture Match Groups | capture_match_groups |
capture_match_groups |
Application Accelerator |
| Deliver | deliver |
deliver |
None |
| Deny (403 Forbidden) | deny |
Not available | None |
| Enable Gzip | enable_gzip |
enable_gzip |
None |
| Enforce HLS cache | Added by Azion | Not available | Live Ingest |
| Filter Request Cookie / Filter Response Cookie | filter_request_cookie |
filter_response_cookie |
Application Accelerator |
| Filter Request Header / Filter Response Header | filter_request_header |
filter_response_header |
None |
| Finish Request Phase | finish_request_phase |
Not available | None |
| Forward Cookies | forward_cookies |
Not available | Application Accelerator |
| No Content (204) | no_content |
Not available | None |
| Optimize Images | optimize_images |
Not available | Image Processor |
| Redirect HTTP to HTTPS | redirect_http_to_https |
Not available | HTTPS on the Workload |
| Redirect To (301 Moved Permanently) | redirect_to_301 |
redirect_to_301 |
None |
| Redirect To (302 Found) | redirect_to_302 |
redirect_to_302 |
None |
| Rewrite Request | rewrite_request |
Not available | Application Accelerator |
| Run Function | run_function |
run_function |
Functions |
| Set Cache Policy | set_cache_policy |
Not available | None |
| Set Connector | set_connector |
Not available | None |
Add Request Cookie and Add Response Cookie
Add Request Cookie adds a cookie in the Set-Cookie header in the Request Phase, and Add Response Cookie does the same in the Response Phase. Both require Application Accelerator turned on in the Application. The argument takes the form cookie-name=cookie-value, and the value can be a variable, as in cookie-name=${arg_cookie}. The Console checks the argument and shows This cookie is not valid when it cannot read one.
In the Response Phase, the argument can carry Set-Cookie attributes after the value, each one after a semicolon (;):
Expires=date, in the formatEEE, d MMM yyyy HH:mm:ss ZDomain=domain-valuePath=path-valueMax-age=number, a TTL in seconds that takes precedence overExpiresSameSite=value; SecureHttpOnly
A cookie with several attributes chains them, as in cookie-name=cookie-value; Domain=domain-value; Path=path-value; SameSite=value. An attribute value can be a variable too, as in Path=${uri}; Domain=${host}. In the API, the Request Phase type is add_request_cookie and the Response Phase type is set_cookie, with the argument in attributes.value.
Add Request Header
Add Request Header adds a header to the request that Azion sends to the origin, in the Request Phase, and requires no Platform Resource. A Response Phase rule adds the header to the response sent to the user instead, with Add Response Header, the API type add_response_header. The argument takes the form Field: value, and the Console refuses any other shape with Header must follow the header-name: value format.
In Azion Console, the header name takes letters, digits, and the characters !#$%&'*+-.^_`|~. The Console refuses any other character in the name with Header name can only use letters, digits and !#$%&'*+-.^_`|~. The header value takes letters, numbers, and these characters:
The Console refuses an empty value with Header value cannot be empty, and a value with a line break or a control character with Header value cannot contain line breaks or control characters. The API checks the value on its own terms: it accepts a backslash, which the Console list leaves out, and it refuses the accented letter é with HTTP 400 and error 25024, Invalid Header.
The argument holds up to 1,600 characters, and a longer one fails with Argument too long. This argument is a valid header:
In the API, the behavior is add_request_header, with the header in attributes.value, such as "Accept: image/webp". A behavior of type add_header is refused with 400 and code 10039. The headers Host, Connection, Range, X-Forward-For, and Cdn-Loop cannot be overwritten or filtered.
Bypass Cache
Bypass Cache sends the requests the rule matches to the origin, and Azion does not cache the response. It runs in the Request Phase and requires Application Accelerator turned on in the Application. The behavior does not change the browser cache, which Set Cache Policy sets through a cache setting. In the API, it is { "type": "bypass_cache" }, with no attributes.
Bypass Cache acts on Azion’s cache and not on the Tiered Cache layer. An Application whose cache settings have Tiered Cache on keeps caching objects in that layer for the Max Age of the cache setting. For how Bypass Cache differs from a cache TTL of 0, refer to Bypass Cache and a TTL of 0. To bypass the cache for one path, refer to Bypass the cache for a path.
Capture Match Groups
Capture Match Groups applies a regular expression to a request field and stores the groups it captures in a temporary array. It runs in either phase and requires Application Accelerator turned on in the Application. Rewrite Request reads the array to build a new path. The array is local, so only the rule that captures it can read it.
| Argument in Azion Console | API attribute | Values | Description |
|---|---|---|---|
| captured array name | captured_array |
String, 1 to 10 characters | The name of the array that holds the captures |
| Subject | subject |
String, 4 to 50 characters | The request field to read, written as a variable such as ${uri} |
| Regex | regex |
String, 1 to 255 characters | The regular expression. Each group to capture goes in parentheses |
Outside the range of the captured array name, the Console shows Captured array name must have at least 1 character. or Captured array name must have at most 10 characters. For a name in another shape, it shows Captured array name must start with a letter and contain only letters or underscores (maximum 10 characters).
A capture is read as %{name[index]}. For example, with capture as the array name, ${uri} as the subject, and ^(.*/)([^/]*)$ as the regular expression, a request for /path/image.jpg fills three entries:
%{capture[0]} = "/path/image.jpg"%{capture[1]} = "/path/"%{capture[2]} = "image.jpg"
A group can also carry a name, in the ?<name> notation, and its capture is then read by that name instead of an index. This regular expression names the two groups path and filename: ^(?<path>.*/)(?<filename>[^/]*)$.
Deliver
Deliver ends the processing of the request and delivers the content to the user, and the rules that follow do not run. It runs in either phase, requires no Platform Resource, and takes no argument. In the API, it is { "type": "deliver" }.
Deny (403 Forbidden)
Deny (403 Forbidden) answers the request with a 403 Forbidden page and ends the processing of the request. It runs in the Request Phase, requires no Platform Resource, and takes no argument. In the API, it is { "type": "deny" }.
Enable Gzip
Enable Gzip compresses the content with gzip when the browser of the user supports it. It runs in either phase, requires no Platform Resource, and is { "type": "enable_gzip" } in the API. To turn compression on for an Application, refer to Compress application responses with gzip.
Enforce HLS cache
Enforce HLS cache imposes the cache policy Azion defines for live HLS transmissions, and requires Live Ingest. Azion adds the behavior to a Request Phase rule every time you select a Live Ingest source. The behavior does two things: it bypasses the cache rules of the Application, and it applies the live HLS policy.
| Object | Cache time |
|---|---|
Playlists, .m3u8 |
5 seconds |
Chunks, .ts |
60 seconds |
To apply the policy to a stream, refer to Enforce HLS cache for live streaming.
Filter Request Cookie
Filter Request Cookie removes a cookie from the request that Azion sends to the origin, and requires Application Accelerator turned on in the Application. A Response Phase rule removes a cookie from the response sent to the user instead, with Filter Response Cookie, the API type filter_response_cookie. The argument is cookie-name to remove the cookie, or cookie-name=cookie-value to remove only that value. In the API, the Request Phase type is filter_request_cookie.
The Console refuses an argument that lacks the cookie name with This filter is not valid, missing cookie name, and one that lacks the cookie value with This filter is not valid, missing cookie value.
Filter Request Header
Filter Request Header removes a header from the request that Azion sends to the origin, and requires no Platform Resource. A Response Phase rule removes a header from the response sent to the user instead, with Filter Response Header, the API type filter_response_header. The argument is the header name, such as Header-Name. In the API, the Request Phase type is filter_request_header.
Five headers cannot be filtered or overwritten:
HostConnectionRangeX-Forward-ForCdn-Loop
Finish Request Phase
Finish Request Phase ends the Request Phase. The behaviors after it in the rule, and the rules after that rule, do not run. It runs in the Request Phase, requires no Platform Resource, and is { "type": "finish_request_phase" } in the API. Azion Console does not offer it in the behavior list: send it through the API, or from the same JSON with azion create rules-engine in Azion CLI.
Forward Cookies
Forward Cookies makes Azion forward the Set-Cookie header that the origin returns to users, even when the response comes from cache. It runs in the Request Phase, requires Application Accelerator turned on in the Application, and is { "type": "forward_cookies" } in the API. A cached response can then carry the Set-Cookie of another user’s session. To keep sessions apart, refer to Forward cookies from the origin to the user.
Azion does not filter the Cookie request header by default, whatever the Forward Cookies configuration, so the cookies a script sets with document.cookie reach the origin.
No Content (204)
No Content (204) answers with 204 instead of the status code the origin returns. It runs in the Request Phase, requires no Platform Resource, and is { "type": "no_content" } in the API.
Optimize Images
Optimize Images applies Image Processor to the requests the rule matches, and requires Image Processor turned on in the Application. It runs in the Request Phase. In the API, it is { "type": "optimize_images" }: it takes no attributes, and a rule can carry it as its only behavior.
Redirect HTTP to HTTPS
Redirect HTTP to HTTPS redirects a request made over HTTP to HTTPS, and does nothing to a request already made over HTTPS. It runs in the Request Phase and is { "type": "redirect_http_to_https" } in the API. It requires HTTPS enabled in the protocol settings of the Workload that receives the request.
Redirect To
Redirect To (301 Moved Permanently) and Redirect To (302 Found) send the user to the URL or URI in the argument, with that status code. Use 301 when a path changes for good, and 302 when the change is temporary. Both behaviors end the processing of the request, run in either phase, and require no Platform Resource. In a Response Phase rule, they run only when the origin returns 404.
The Console asks for the argument with Redirect target is required, and refuses a space in it with Redirect target cannot contain spaces, use %20 instead. It refuses a target with another start with Redirect target must start with /, http://, https://, #, ?, ${variable} or %{captured}, and a variable in another format with Variables must use the ${lowercase_name} format. In the API, the types are redirect_to_301 and redirect_to_302, with the target in attributes.value. This behavior sends a reader of a FAQ to its English version:
| Behavior | Argument |
|---|---|
| Redirect To (302 Found) | /en-us/faq |
Rewrite Request
Rewrite Request changes the path of the resource that Azion requests from the origin. It runs in the Request Phase, requires Application Accelerator turned on in the Application, and is rewrite_request in the API, with the new path in attributes.value. The new path can combine a string, the variables of the Request Phase, and the captures of Capture Match Groups, written as %{name[index]}. The Console refuses a path with another start with Argument should start with /, ${uri}, ${request_uri}, or ${domain}.
For example, two behaviors in one rule send a request for /original/image.jpg to the origin as /new/image.jpg:
| Behavior | Argument |
|---|---|
| Capture Match Groups | captured array name capture, Subject ${uri}, Regex /original/(.*) |
| Rewrite Request | /new/%{capture[1]} |
Run Function
Run Function invokes a Function Instance of the Application on what the rule matches. It runs in either phase and requires Functions turned on in the Application, and a new Application has Functions on. In the Response Phase, it runs only Functions written in Lua. In Azion Console, the rule form states Only functions with Lua runtime are available for Response phase., and the Function Instance form states Only Lua functions can be used in the Response phase.
In the API, attributes.value holds the ID of the Function Instance, not of the Function, as in { "type": "run_function", "attributes": { "value": <function-instance-id> } }. To create a Function Instance, refer to Instantiate a function on an application.
Set Cache Policy
Set Cache Policy applies a cache setting to the requests the rule matches, which is how a cache setting reaches a request. It runs in the Request Phase and requires no other Platform Resource. The cache setting has to exist before a rule can apply it, and Cache quickstart creates a first cache setting and the rule that applies it.
The cache setting holds how long an object stays in cache. Its Application Accelerator fields hold the variations that set the cache key. In the API, attributes.value holds the ID of the cache setting. The API returns that ID as an integer, even when the request sends it as a string. A cache setting that a rule applies cannot be deleted: the API answers 400 with code 21014.
Set Connector
Set Connector sends the requests the rule matches to a Connector, which routes them to the origin. It runs in the Request Phase and requires no Platform Resource, so a rule with ${uri} and Set Connector works in an Application without Application Accelerator. In the API, attributes.value holds the ID of the Connector, as the API section shows.
API
Every rule operation is authenticated and sits under https://api.azion.com/v4/workspace/applications/<application-id>. A request carries a personal token in the Authorization header under the Token scheme. A request with a body also carries Content-Type: application/json.
| Operation | Request Phase | Response Phase |
|---|---|---|
| Create a rule | POST /request_rules |
POST /response_rules |
| List the rules of the phase | GET /request_rules |
GET /response_rules |
| Retrieve a rule | GET /request_rules/{request_rule_id} |
GET /response_rules/{response_rule_id} |
| Replace a rule | PUT /request_rules/{request_rule_id} |
PUT /response_rules/{response_rule_id} |
| Update part of a rule | PATCH /request_rules/{request_rule_id} |
PATCH /response_rules/{response_rule_id} |
| Delete a rule | DELETE /request_rules/{request_rule_id} |
DELETE /response_rules/{response_rule_id} |
| Reorder the rules | PUT /request_rules/order |
PUT /response_rules/order |
A create answers 202 with a state of pending, and a list answers 200. The reorder call takes an order array that lists the rule IDs of the phase in their new order.
This call creates a Request Phase rule that sends every request of the Application to a Connector:
The response carries 202 and a state of pending. The excerpt keeps the rule as the platform stored it:
The platform adds description, an empty string when the create sends none, and order, the position of the rule in its phase. The same body with ${request_uri} in place of ${uri} fails with code 25047 in an Application without Application Accelerator.
CLI
Azion CLI creates a rule with azion create rules-engine, which reads the rule from a JSON file in the shape the API takes. --phase names the phase, and azion create rules-engine has no default for it: in a terminal, the command asks for the phase, and with no terminal it fails with Error: Failed to parse your response.
This file applies a cache setting to every request whose path starts with /static/:
Save it as rule.json, replace <cache-setting-id> with the ID of a cache setting of the Application, and create the rule:
The CLI refuses two older shapes of a rule file. A criterion with input_value instead of argument fails with json: unknown field "input_value". A behavior written as {"type":"set_cache_settings","cache_settings_id":"<id>"} fails with data failed to match schemas in oneOf(RequestPhaseBehaviorRequest): the behavior is set_cache_policy, with the ID in attributes.value.
Six commands cover the rules of a phase. Each takes --application-id and --phase, and a command that acts on one rule takes its ID in --rule-id:
| Command | What it does | Flags |
|---|---|---|
azion create rules-engine |
Creates a rule from a JSON file | --application-id, --phase, --file |
azion list rules-engine |
Lists the rules of a phase | --application-id, --phase, --details, --filter, --order-by, --page, --page-size |
azion describe rules-engine |
Returns one rule | --application-id, --phase, --rule-id |
azion update rules-engine |
Changes a rule from a JSON file | --application-id, --phase, --rule-id, --file |
azion delete rules-engine |
Deletes a rule | --application-id, --phase, --rule-id |
azion update rules-engine-order |
Reorders the rules of a phase | --application-id, --phase, --rule-ids |
--rule-ids takes the rule IDs of the phase in their new order, separated by commas, such as 123,456,789. On azion list rules-engine and azion delete rules-engine, --phase defaults to request.
Errors
A rejected rule returns an errors array. Each entry carries a code, a title, a detail, the status, and a source pointer that names the field. Some entries add a meta object. This body answers a rule with ${request_uri} in an Application without Application Accelerator:
| Code | Title | Status | What causes it | What to do |
|---|---|---|---|---|
10039 |
Invalid Choice | 400 | A behavior type that is not a valid choice, such as add_header |
Send a type from the behavior table, such as add_request_header |
21014 |
Cannot Delete Cache Setting | 400 | Deleting a cache setting that a rule applies with set_cache_policy |
Remove the behavior or the rule that applies it, then delete the cache setting |
25010 |
Behavior Marked As Final | 400 | A behavior after a final behavior, such as Deliver | Make the final behavior the last of the rule |
25011 |
Duplicated Behavior | 400 | A behavior that a rule takes once, such as Bypass Cache, repeated in the rule | Keep one |
25012 |
Incompatible Behavior | 400 | Set Cache Policy beside Deny (403 Forbidden), Redirect To, or No Content (204) | Move one of them to another rule |
25024 |
Invalid Header | 400 | A header argument the API does not accept, such as a value with é |
Remove the character the API refuses |
25047 |
Missing Required Modules | 400 | A criterion variable whose Platform Resource is off, such as ${request_uri} without Application Accelerator |
Turn on Application Accelerator, as Main Settings shows, or match on ${uri} |
For 10039, the detail reads "add_header" is not a valid choice., the source pointer names the behavior, as in /data/behaviors/0/type, and meta.input repeats the value. For 25047, meta.missing_required_modules names the modules key of the Platform Resource to turn on.