Azure CDN Rules Engine Match Condition and Feature Details

 

Updated: July 8, 2016

Applies To: Microsoft Azure

This topic lists detailed descriptions of the available match conditions and features for Azure Content Delivery Network (CDN) Rules Engine.

The manner in which special characters will be treated varies according to how a match condition or feature handles text values. A match condition or feature may interpret text in one of the following ways:

  1. Literal Values
  2. Wildcard Values
  3. Regular Expressions

Literal Values

Text that is interpreted as a literal value will treat all special characters, with the exception of the % symbol, as a part of the value that must be matched. In other words, a literal match condition set to \'*'\ will only be satisfied when that exact value (i.e., \'*'\) is found.

A percentage symbol is used to indicate URL encoding (e.g., %20).

Wildcard Values (Special Characters)

Text that is interpreted as a wildcard value will assign additional meaning to special characters. The following table describes how the following set of characters will be interpreted.

CharacterDescription
\A backslash is used to escape any of the characters specified in this table. A backslash must be specified directly before the special character that should be escaped.
For example, the following syntax escapes an asterisk: \*
%A percentage symbol is used to indicate URL encoding (e.g., %20).
*An asterisk is a wildcard that represents one or more characters.
SpaceA space character indicates that a match condition may be satisfied by either of the specified values or patterns.
'value'A single quote does not have special meaning. However, a set of single quotes is used to indicate that a value should be treated as a literal value. It can be used in the following ways:

- It allows a match condition to be satisfied whenever the specified value matches any portion of the comparison value. For example, 'ma' would match any of the following strings:

/business/marathon/asset.htm
map.gif
/business/template.map

- It allows a special character to be specified as a literal character. For example, you may specify a literal space character by enclosing a space character within a set of single quotes (i.e., ' ' or 'sample value').
- It allows a blank value to be specified. Specify a blank value by specifying a set of single quotes (i.e., '').

Important:
- If the specified value does not contain a wildcard, then it will automatically be considered a literal value. This means that it is not necessary to specify a set of single quotes.
- If a backslash does not escape another character in this table, then it will be ignored when specified within a set of single quotes.
- Another way to specify a special character as a literal character is to escape it using a backslash (i.e., \).

Regular Expressions

Regular expressions define a pattern that will be searched for within a text value. Regular expression notation defines specific meanings to a variety of symbols. The following table indicates how special characters are treated by match conditions and features that support regular expressions.

Special CharacterDescription
\A backslash escapes the character the follows it. This causes that character to be treated as a literal value instead of taking on its regular expression meaning. For example, the following syntax escapes an asterisk: \*
%The meaning of a percentage symbol depends on its usage.

 %{HTTPVariable}: This syntax identifies an HTTP variable.
%{HTTPVariable%Pattern}: This syntax uses a percentage symbol to identify an HTTP variable and as a delimiter.
\%: Escaping a percentage symbol allows it to be used as a literal value or to indicate URL encoding (e.g., \%20).
*An asterisk allows the preceding character to be matched zero or more times.
SpaceA space character is typically treated as a literal character.
'value'Single quotes are treated as literal characters. A set of single quotes does not have special meaning.

A match condition identifies specific types of requests for which a set of features will be performed.

For example, it may be used to filter requests for content at a particular location, requests generated from a particular IP address or country, or by header information.

Always

The Always match condition is designed to apply a default set of features to all requests.

Device

The Device match condition identifies requests made from a mobile device based on its properties. Mobile device detection is achieved through WURFL. WURFL capabilities and their CDN Rules Engine variables are listed below.

System_CAPS_ICON_tip.jpg Tip

The variables below are supported in the Modify Client Request Header and Modify Client Response Header features.

CapabilityVariableDescriptionSample Value(s)
Brand Name%{wurfl_cap_brand_name}A string that indicates the brand name of the device.Samsung
Device OS%{wurfl_cap_device_os}A string that indicates the operating system installed on the device.IOS
Device OS Version%{wurfl_cap_device_os_version}A string that indicates the version number of the OS installed on the device.1.0.1
Dual Orientation%{wurfl_cap_dual_orientation}A Boolean that indicates whether the device supports dual orientation.true
HTML Preferred DTD%{wurfl_cap_html_preferred_dtd}A string that indicates the mobile device's preferred document type definition (DTD) for HTML content.none
xhtml_basic
html5
Image Inlining%{wurfl_cap_image_inlining}A Boolean that indicates whether the device supports Base64 encoded images.false
Is Android%{wurfl_vcap_is_android}A Boolean that indicates whether the device uses the Android OS.true
Is IOS%{wurfl_vcap_is_ios}A Boolean that indicates whether the device uses iOS.false
Is Smart TV%{wurfl_cap_is_smarttv}A Boolean that indicates whether the device is a smart TV.false
Is Smartphone%{wurfl_vcap_is_smartphone}A Boolean that indicates whether the device is a smartphone.true
Is Tablet%{wurfl_cap_is_tablet}A Boolean that indicates whether the device is a tablet. This is an OS-independent description.true
Is Wireless Device%{wurfl_cap_is_wireless_device}A Boolean that indicates whether the device is considered a wireless device.true
Marketing Name%{wurfl_cap_marketing_name}A string that indicates the device's marketing name.BlackBerry 8100 Pearl
Mobile Browser%{wurfl_cap_mobile_browser}A string that indicates the browser used to request content from the device.Chrome
Mobile Browser Version%{wurfl_cap_mobile_browser_version}A string that indicates the version of the browser used to request content from the device.31
Model Name%{wurfl_cap_model_name}A string that indicates the device's model name.s3
Progressive Download%{wurfl_cap_progressive_download}A Boolean that indicates whether the device supports the playback of audio/video while it is still being downloaded.true
Release Date%{wurfl_cap_release_date}A string that indicates the year and month on which the device was added to the WURFL database.

Format: yyyy_mm
2013_december
Resolution Height%{wurfl_cap_resolution_height}An integer that indicates the device's height in pixels.768
Resolution Width%{wurfl_cap_resolution_width}An integer that indicates the device's width in pixels.1024

Location

These match conditions are designed to identify requests based on the requester's location.

NamePurpose
AS NumberIdentifies requests that originate from a particular network.
CountryIdentifies requests that originate from the specified countries.

Origin

These match conditions are designed to identify requests that point to CDN storage or a customer origin server.

NamePurpose
CDN OriginIdentifies requests for content stored on CDN storage.
Customer OriginIdentifies requests for content stored on a specific customer origin server.

Request

These match conditions are designed to identify requests based on their properties.

NamePurpose
Client IP AddressIdentifies requests that originate from a particular IP address.
Cookie ParameterChecks the cookies associated with each request for the specified value.
Cookie Parameter RegexChecks the cookies associated with each request for the specified regular expression.
Edge CnameIdentifies requests that point to a specific edge CNAME.
Referring DomainIdentifies requests that were referred from the specified hostname(s).
Request Header LiteralIdentifies requests that contain the specified header set to a specified value(s).
Request Header RegexIdentifies requests that contain the specified header set to a value that matches the specified regular expression.
Request Header WildcardIdentifies requests that contain the specified header set to a value that matches the specified pattern.
Request MethodIdentifies requests by their HTTP method.
Request SchemeIdentifies requests by their HTTP protocol.

URL

These match conditions are designed to identify requests based on their URLs.

NamePurpose
URL Path DirectoryIdentifies requests by their relative path.
URL Path ExtensionIdentifies requests by their filename extension.
URL Path FilenameIdentifies requests by their filename.
URL Path LiteralCompares a request's relative path to the specified value.
URL Path RegexCompares a request's relative path to the specified regular expression.
URL Path WildcardCompares a request's relative path to the specified pattern.
URL Query LiteralCompares a request's query string to the specified value.
URL Query ParameterIdentifies requests that contain the specified query string parameter set to a value that matches a specified pattern.
URL Query RegexIdentifies requests that contain the specified query string parameter set to a value that matches a specified regular expression.
URL Query WildcardCompares the specified value(s) against the request's query string.

A feature defines the type of action that will be applied to the type of request identified by a set of match conditions.

Access

These features are designed to control access to content.

System_CAPS_ICON_note.jpg Note

Token auth is not generally available yet, but will be supported in a future release.

NamePurpose
Deny AccessDetermines whether all requests are rejected with a 403 Forbidden response.
Token AuthDetermines whether Token-Based Authentication will be applied to a request.
Token Auth Denial CodeDetermines the type of response that will be returned to a user when a request is denied due to Token-Based Authentication.
Token Auth Ignore URL CaseDetermines whether URL comparisons made by Token-Based Authentication will be case-sensitive.
Token Auth ParameterDetermines whether the Token-Based Authentication query string parameter should be renamed.

Caching

These features are designed to customize when and how content is cached.

NamePurpose
Bandwidth ParametersDetermines whether bandwidth throttling parameters (i.e., ec_rate and ec_prebuf) will be active.
Bandwidth ThrottlingThrottles the bandwidth for the response provided by our edge servers.
Bypass CacheDetermines whether the request can leverage our caching technology.
Cache-Control Header TreatmentControls the generation of Cache-Control headers by the edge server when External Max-Age feature is active.
Cache-Key Query StringDetermines whether the cache-key will include or exclude query string parameters associated with a request.
Cache-Key RewriteRewrites the cache-key associated with a request.
Complete Cache FillDetermines what happens when a request results in a partial cache miss on an edge server.
Compress File TypesDefines the file formats that will be compressed on the server.
Default Internal Max-AgeDetermines the default max-age interval for edge server to origin server cache revalidation.
Expires Header TreatmentControls the generation of Expires headers by an edge server when the External Max-Age feature is active.
External Max-AgeDetermines the max-age interval for browser to edge server cache revalidation.
Force Internal Max-AgeDetermines the max-age interval for edge server to origin server cache revalidation.
H.264 Support (HTTP Progressive Download)Determines the types of H.264 file formats that may be used to stream content.
Honor No-Cache RequestDetermines whether an HTTP client's no-cache requests will be forwarded to the origin server.
Ignore Origin No-CacheDetermines whether our CDN will ignore certain directives served from an origin server.
Ignore Unsatisfiable RangesDetermines the response that will be returned to clients when a request generates a 416 Requested Range Not Satisfiable status code.
Internal Max-StaleControls how long past the normal expiration time a cached asset may be served from an edge server when the edge server is unable to revalidate the cached asset with the origin server.
Partial Cache SharingDetermines whether a request can generate partially cached content.
Prevalidate Cached ContentDetermines whether cached content will be eligible for early revalidation before its TTL expires.
Refresh Zero-Byte Cache FilesDetermines how an HTTP client's request for a 0-byte cache asset is handled by our edge servers.
Set Cacheable Status CodesDefines the set of status codes that can result in cached content.
Stale Content Delivery on ErrorDetermines whether expired cached content will be delivered when an error occurs during cache revalidation or when retrieving the requested content from the customer origin server.
Stale While RevalidateImproves performance by allowing our edge servers to serve stale client to the requester while revalidation takes place.
CommentThe Comment feature allows a note to be added within a rule.

Headers

These features are designed to add, modify, or delete headers from the request or response.

NamePurpose
Age Response HeaderDetermines whether an Age response header will be included in the response sent to the requester.
Debug Cache Response HeadersDetermines whether a response may include the X-EC-Debug response header which provides information on the cache policy for the requested asset.
Modify Client Request HeaderOverwrites, appends, or deletes a header from a request.
Modify Client Response HeaderOverwrites, appends, or deletes a header from a response.
Set Client IP Custom HeaderAllows the IP address of the requesting client to be added to the request as a custom request header.

Logs

These features are designed to customize the data stored in raw log files.

NamePurpose
Custom Log Field 1Determines the format and the content that will be assigned to the custom log field in a raw log file.
Log Query StringDetermines whether a query string will be stored along with the URL in access logs.

Optimize

These features determine whether a request will undergo the optimizations provided by Edge Optimizer.

NamePurpose
Edge OptimizerDetermines whether Edge Optimizer can be applied to a request.
Edge Optimizer – Instantiate ConfigurationInstantiates or activates the Edge Optimizer configuration associated with a site.

Origin

These features are designed to control how the CDN communicates with an origin server.

NamePurpose
Maximum Keep-Alive RequestsDefines the maximum number of requests for a Keep-Alive connection before it is closed.
Proxy Special HeadersDefines the set of CDN-specific request headers that will be forwarded from an edge server to an origin server.

Specialty

These features provide advanced functionality that should only be used by advanced users.

NamePurpose
Cacheable HTTP MethodsDetermines the set of additional HTTP methods that can be cached on our network.
Cacheable Request Body SizeDefines the threshold for determining whether a POST response can be cached.

URL

These features allow a request to be redirected or rewritten to a different URL.

NamePurpose
Follow RedirectsDetermines whether requests can be redirected to the hostname defined in the Location header returned by a customer origin server.
URL RedirectRedirects requests via the Location header.
URL RewriteRewrites the request URL.

Web Application Firewall

The Web Application Firewall feature determines whether a request will be screened by Web Application Firewall.

Show: