HTTP variables for Azure CDN rules engine
HTTP variables provide the means through which you can retrieve HTTP request and response metadata. This metadata can then be used to dynamically alter a request or a response. The use of HTTP variables is restricted to the following rules engine features:
- Cache-Key Rewrite
- Modify Client Request Header
- Modify Client Response Header
- URL Redirect
- URL Rewrite
Definitions
The following table describes the supported HTTP variables. A blank value is returned when GEO metadata (for example, postal code) is unavailable for a particular request.
| Name | Variable | Description | Sample value |
|---|---|---|---|
| ASN (Requester) | %{geo_asnum} | Indicates the requester's AS number. Deprecated: %{virt_dst_asnum}. This variable has been deprecated in favor of %{geo_asnum}. Although a rule that uses this deprecated variable continues to work, you should update it to use the new variable. |
AS15133 |
| City (Requester) | %{geo_city} | Indicates the requester's city. | Los Angeles |
| Continent (Requester) | %{geo_continent} | Indicates the requester's continent through its abbreviation. Valid values are: AF: Africa AS: Asia European Union (EU): Europe NA: North America OC: Oceania Software Assurance (SA): South America Deprecated: %{virt_dst_continent}. This variable has been deprecated in favor of %{geo_continent}. Although a rule that uses this deprecated variable continues to work, you should update it to use the new variable. |
N/A |
| Cookie Value | %{cookie_Cookie} | Returns the value corresponding to the cookie key identified by the Cookie term. | Sample Usage: %{cookie__utma} Sample Value: 111662281.2.10.1222100123 |
| Country/Region (Requester) | %{geo_country} | Indicates the requester's country/region of origin through its country/region code. Deprecated: %{virt_dst_country}. This variable has been deprecated in favor of %{geo_country}. Although a rule that uses this deprecated variable continues to work, you should update it to use the new variable. |
US |
| Designated Market Area (Requester) | %{geo_dma_code} | Indicates the requester's media market by its region code. This field is only applicable to requests that originate from the United States. |
745 |
| HTTP Request Method | %{request_method} | Indicates the HTTP request method. | GET |
| HTTP Status Code | %{status} | Indicates the HTTP status code for the response. | 200 |
| IP Address (Requester) | %{virt_dst_addr} | Indicates the requester's IP address. | 192.168.1.1 |
| Latitude (Requester) | %{geo_latitude} | Indicates the requester's latitude. | 34.0995 |
| Longitude (Requester) | %{geo_longitude} | Indicates the requester's longitude. | -118.4143 |
| Metropolitan Statistical Area (Requester) | %{geo_metro_code} | Indicates the requester's metropolitan area. This field is only applicable to requests that originate from the United States. |
745 |
| Port (Requester) | %{virt_dst_port} | Indicates the requester's ephemeral port. | 55885 |
| Postal Code (Requester) | %{geo_postal_code} | Indicates the requester's postal code. | 90210 |
| Query String Found | %{is_args} | The value for this variable varies according to whether the request contains a query string. - Query String Found: ? - No Query String: NULL |
? |
| Query String Parameter Found | %{is_amp} | The value for this variable varies according to whether the request contains at least one query string parameter. - Parameter Found: & - No Parameters: NULL |
& |
| Query String Parameter Value | %{arg_<parameter>} | Returns the value corresponding to the query string parameter identified by the <parameter> term. | Sample Usage: %{arg_language} Sample Query String Parameter: ?language=en Sample Value: en |
| Query String Value | %{query_string} | Indicates the entire query string value defined in the request URL. | key1=val1&key2=val2&key3=val3 |
| Referrer Domain | %{referring_domain} | Indicates the domain defined in the Referrer request header. | <www.google.com> |
| Region (Requester) | %{geo_region} | Indicates the requester's region (for example, state or province) through its alphanumeric abbreviation. | CA |
| Request Header Value | %{http_RequestHeader} | Returns the value corresponding to the request header identified by the RequestHeader term. If the name of the request header contains a dash (for example, User-Agent), replace it with an underscore (for example, User_Agent). |
Sample Usage: %{http_Connection} Sample Value: Keep-Alive |
| Request Host | %{host} | Indicates the host defined in the request URL. | <www.mydomain.com> |
| Request Protocol | %{request_protocol} | Indicates the request protocol. | HTTP/1.1 |
| Request Scheme | %{scheme} | Indicates the request scheme. | HTTP |
| Request URI (Relative) | %{request_uri} | Indicates the relative path, including the query string, defined in the request URI. | /marketing/foo.js?loggedin=true |
| Request URI (Relative without query string) | %{URI} | Indicates the relative path to the requested content. Key information: - This relative path excludes the query string. - This relative path reflects URL rewrites. A URL is rewritten under the following conditions: - URL Rewrite Feature: This feature rewrites the relative path defined in the request URI. - Edge CNAME URL: This type of request is rewritten to the corresponding CDN URL. |
/800001/corigin/rewrittendir/foo.js |
| Request URI | %{request} | Describes the request. Syntax: <HTTP method> <relative path> <HTTP protocol> |
GET /marketing/foo.js?loggedin=true HTTP/1.1 |
| Response Header Value | %{resp_<ResponseHeader>} | Returns the value corresponding to the response header identified by the <ResponseHeader> term. If the name of the response header contains a dash (for example, User-Agent), replace it with an underscore (for example, User_Agent). |
Sample Usage: %{resp_Content_Length} Sample Value: 100 |
Usage
The following table describes the proper syntax for specifying an HTTP variable.
| Syntax | Example | Description |
|---|---|---|
| %{<HTTPVariable>} | %{host} | Use this syntax to get the entire value corresponding to the specified <HTTPVariable>. |
| %{<HTTPVariableDelimiter>} | %{host,} | Use this syntax to set the case for the entire value corresponding to the specified <HTTPVariableDelimiter>. |
| %{<HTTPVariableDelimiterExpression>} | %{host/=^www.([^.]+).([^.:]+)/cdn.$2.$3:80} | Use a regular expression for <HTTPVariableDelimiterExpression> to replace, delete, or manipulate an HTTP variable's value. |
HTTP variable names only support alphabetic characters and underscores. Convert unsupported characters to underscores.
Delimiter reference
A delimiter can be specified after an HTTP variable to achieve any of the following effects:
Transform the value associated with the variable.
Example: Convert the entire value to lowercase.
Delete the value associated with the variable.
Manipulate the value associated with the variable.
Example: Use regular expressions to change the value associated with the HTTP variable.
The delimiters are described in the following table.
| Delimiter | Description |
|---|---|
| := | Indicates that a default value is assigned to the variable when it's either: - Missing - Set to NULL. |
| :+ | Indicates that a default value is assigned to the variable when a value has been assigned to it. |
| : | Indicates that a substring of the value assigned to the variable is expanded. |
| # | Indicates that the pattern specified after this delimiter should be deleted when it's present at the beginning of the value associated with the variable. |
| % | Indicates that the pattern specified after this delimiter should be deleted when it's present at the end of the value associated with the variable. This definition is only applicable when the % symbol is used as a delimiter. |
| / | Delimits an HTTP variable or a pattern. |
| // | Find and replace all instances of the specified pattern. |
| /= | Find, copy, and rewrite all occurrences of the specified pattern. |
| , | Convert the value associated with the HTTP variable to lowercase. |
| ^ | Convert the value associated with the HTTP variable to uppercase. |
| ,, | Convert all instances of the specified character in the value associated with the HTTP variable to lowercase. |
| ^^ | Convert all instances of the specified character in the value associated with the HTTP variable to uppercase. |
Exceptions
The following table describes circumstances under which the specified text isn't treated as an HTTP variable.
| Condition | Description | Example |
|---|---|---|
| Escaping % symbol | The percentage symbol can be escaped by using a backslash. The sample value to the right is treated as a literal value and not as an HTTP variable. |
%{host} |
| Unknown variables | An empty string is always returned for unknown variables. | %{unknown_variable} |
| Invalid characters or syntax | Variables that contain invalid characters or syntax are treated as literal values. Example #1: The specified value contains an invalid character (for example, -). Example #2: The specified value contains a double set of curly braces. Example #3: The specified value is missing a closing curly brace. |
Example #1: %{resp_user-agent} Example #2: %{{host}} Example #3: %{host |
| Missing variable name | A NULL value is always returned when a variable isn't specified. | %{} |
| Trailing characters | Characters that trail a variable are treated as literal values. The sample value to the right contains a trailing curly brace that gets treated as a literal value. |
%{host}} |
Setting default header values
A default value can be assigned to a header when it meets any of the following conditions:
- Missing/unset
- Set to NULL.
The following table describes how to define a default value.
| Condition | Syntax | Example | Description |
|---|---|---|---|
| Set a header to a default value when it meets any of the following conditions: - Missing Header - Header value is set to NULL. |
%{Variable:=Value} | %{http_referrer:=unspecified} | The Referrer header is set to unspecified only when it's either missing or set to NULL. No action takes place if it has been set. |
| Set a header to a default value when it's missing. | %{Variable=Value} | %{http_referrer=unspecified} | The Referrer header is set to unspecified only when it's missing. No action takes place if it has been set. |
| Set the header to a default value when it doesn't meet any of the following conditions: - Missing - Set to NULL. |
%{Variable:+Value} | %{http_referrer:+unspecified} | The Referrer header is set to unspecified only when a value has been assigned to it. No action takes place if it's either missing or set to NULL. |
Manipulating variables
Variables can be manipulated in the following ways:
- Expanding substrings
- Removing patterns
Substring expansion
By default, a variable expands to its full value. Use the following syntax to only expand a substring of the variable's value.
%<Variable>:<Offset>:<Length>}
Key information:
The value assigned to the Offset term determines the starting character of the substring:
- Positive: The starting character of the substring is calculated from the first character in the string.
- Zero: The starting character of the substring is the first character in the string.
- Negative: The starting character of the substring is calculated from the last character in the string.
The length of the substring gets determined by the Length term:
- Omitted: Omitting the Length term allows the substring to include all characters between the starting character and the end of the string.
- Positive: Determines the length of the substring from the starting character to the right.
- Negative: Determines the length of the substring from the starting character to the left.
Example:
The following example relies on the following sample request URL:
HTTPS:\//cdn.mydomain.com/folder/marketing/myconsultant/proposal.html
The following string demonstrates various methods for manipulating variables:
HTTPS:\//www%{http_host:3}/mobile/%{request_uri:7:10}/%{request_uri:-5:-8}.htm
Based on the sample request URL, the above variable manipulation produces the following value:
HTTPS:\//www.mydomain.com/mobile/marketing/proposal.htm
Pattern removal
Text that matches a specific pattern can be removed from either the beginning or the end of a variable's value.
| Syntax | Action |
|---|---|
| %{Variable#Pattern} | Remove text when the specified pattern is found at the beginning of a variable's value. |
| %{Variable%Pattern} | Remove text when the specified pattern is found at the end of a variable's value. |
Example:
In this sample scenario, the request_uri variable is set to:
/800001/myorigin/marketing/product.html?language=en-US
The following table demonstrates how this syntax works.
| Sample syntax | Results | Description |
|---|---|---|
| %{request_uri#/800001}/customerorigin | /customerorigin/myorigin/marketing/product.html?language=en-US | Because the variable starts with the pattern, it was replaced. |
| %{request_uri%html}htm | /800001/myorigin/marketing/product.html?language=en-US | Because the variable doesn't end with the pattern, there was no change. |
Find and replace
The find and replace syntax is described in the following table.
| Syntax | Action |
|---|---|
| %{Variable/Find/Replace} | Find and replace first occurrence of the specified pattern. |
| %{Variable//Find/Replace} | Find and replace all occurrences of the specified pattern. |
| %{Variable^} | Convert the entire value to uppercase. |
| %{Variable^Find} | Convert the first occurrence of the specified pattern to uppercase. |
| %{Variable,} | Convert the entire value to lowercase. |
| %{Variable,Find} | Convert the first occurrence of the specified pattern to lowercase. |
Find and rewrite
For a variation on find and replace, use the text that matches the specified pattern when rewriting it. The find and rewrite syntax is described in the following table.
| Syntax | Action |
|---|---|
| %{Variable/=Find/Rewrite} | Find, copy, and rewrite all occurrences of the specified pattern. |
| %{Variable/^Find/Rewrite} | Find, copy, and rewrite the specified pattern when it occurs at the start of the variable. |
| %{Variable/$Find/Rewrite} | Find, copy, and rewrite the specified pattern when it occurs at the end of the variable. |
| %{Variable/Find} | Find and delete all occurrences of the specified pattern. |
Key information:
Expand text that matches the specified pattern by specifying a dollar sign followed by a whole integer (for example, $1).
Multiple patterns can be specified. The order in which the pattern is specified determines the integer that is assigned to it. In the following example, the first pattern matches "Www.," the second pattern matches the second-level domain, and the third pattern matches the top-level domain:
%{host/=^www\.([^\.]+)\.([^\.:]+)/cdn.$2.$3:80}The rewritten value can consist of any combination of text and these placeholders.
In the previous example, the hostname is rewritten to
cdn.$2.$3:80(for example, cdn.mydomain.com:80).The case of a pattern placeholder (for example, $1) can be modified through the following flags:
U: Uppercase the expanded value.
Sample syntax:
%{host/=^www\.([^\.]+)\.([^\.:]+)/cdn.$U2.$3:80}L: Lowercase the expanded value.
Sample syntax:
%{host/=^www\.([^\.]+)\.([^\.:]+)/cdn.$L2.$3:80}
An operator must be specified before the pattern. The specified operator determines the pattern-capturing behavior:
=: Indicates that all occurrences of the specified pattern must be captured and rewritten.^: Indicates that only text that starts with the specified pattern is captured.$: Indicates that only text that ends with the specified pattern is captured.
If you omit the /Rewrite value, the text that matches the pattern is deleted.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for