Request matches
These match tags use certain request properties and apply metadata to the request when the conditions are met. For example, you can apply metadata based on whether or not the request headers include a particular cookie with a particular value.
📘Case sensitivity
Tag names and content strings are case sensitive. For tag names, use lower-case throughout. The match tag value is matched in a case-sensitive manner.
ext
Matches the file extension in the request URL and is recursive. This particular match type is not case sensitive, that is, listing gif
as the extension to match will also match extensions GIF
, Gif
, giF
and similar.
The following example metadata revalidates all files with the extension .exe
.
<match:ext value="exe">
<revalidate>1046581729</revalidate>
</match:ext>
The value argument accepts a space-separated list of strings that are the file extensions to match. Again, this match is not case sensitive.
Note that this match is applied correctly in cases where the request URL includes a query string. Given the example above, http://www.example.com/sample.exe?id=375
would match the extension exe
. The extension is everything between the final dot .
in the last path segment and the end of the URL, the beginning of the query string (if present), or beginning of parameters (if present). Parameters are separated from the extension by a semicolon ;
and may contain variable=value
settings.
cookie
This match type matches on cookies received from the client (browser) in the Cookie
header. Useful if the site caches responses separately based on the presence of a cookie. For example, a cookie that identifies the language of the end client might be used to separate English content from French content in cache. Using this match, you would be able to invalidate one set of content without invalidating the other set. The syntax for this match type is:
<match:cookie name="user_id" op="present" value="">
Match tag properties for match cookie are:
-
name: name of the cookie
The name attribute of this match type allows for wildcard characters
*
that will match any character in a cookie name. In this feature, the wildcard will be "non-greedy" and will match zero or more characters. This was introduced in 4.4.Examples:
-
*sessionid*
matches:sessionid
,xxsessionid
,sessionidyy
,xxsessionidyy
, etc. -
*sessionid
matches:sessionid
andxxsessionid
but notsessionidyy
orxxsession- idyy
. -
sessionid*
matches:sessionid
andsessionidyy
but notxxsessionid
orxxsession- idyy
. -
*
matches all cookie names. -
*a*a*a*
matches a cookie name that has three lettersa
anywhere in it.
If only one wildcard is used in a name and it's the last character, it would be equivalent to setting the name-prefix-match property to on and not using the wildcard character. In order to avoid any conflicts between name-prefix-match and the new wildcard support, the edge server will ignore the special meaning of wildcards in the cookie name when
name-prefix-match
is on and translate them literally as it does now (again, this is for backward compatibility).Given that browsers don't enforce any standards for cookie names, it's possible for sites to use the wildcard character as part of the name — however, that's very unlikely. In order to support this corner case, users can "escape" the wildcard by using a backslash in front of the wildcard to mean a literal wildcard. In turn, if the backslash is part of the cookie name (again, very unlikely), users will have to escape the backslash by another backslash. The purpose of the backslash is to force the edge server to translate the character following it literally.
Examples:
-
sessionid\*
matches "sessionid*" exactly. -
sessionid\*\\
matches "sessionid *" exactly. -
sessionid\**
would match a cookie name that begins with "sessionid*". -
sessioni\d
would match "sessionid" exactly. Notice that this example escaped the letter "d" which is not special. Edge servers will allow for this in case a user accidentally escapes a non-special character.
-
-
name-prefix-match: sets whether the string in "name" must match the
cookie name exactly or be a prefix of the full cookie name. The property is a simple
Boolean and defaults to "off ". This is particularly useful for matching "sessionid"
cookies, where the cookie name includes a unique string but has a constant prefix. -
value: The full or partial value the cookie should have.
-
op: Match operation. Must be one of the following:
-
present: The given cookie name must be present in the HTTP headers.
-
missing: The given cookie name must not be present in the HTTP headers.
-
strcmp: The cookie must have exactly the given value.
-
strcasecmp: Same as strcmp but not case sensitive.
-
strstr: The cookie must have the given substring (specified as the value).
-
strcasestr: same as strstr but not case sensitive.
Examples:
- Match only if a cookie named "session_id" exists:
<match:cookie name="session_id" op="present" value="">
- Match only if a cookie named "user_id" doesn't exist:
<match:cookie name="user_id" op="missing" value="">
- Match only if a cookie named "logged_in" is set to "yes":
<match:cookie name="logged_in" op="strcmp" value="yes">
- Same thing matching "yes" case insensitively:
<match:cookie name="logged_in" op="strcasecmp" value="yes">
- Match only if a cookie named "custtype" has "_vip" somewhere within it:
<match:cookie name="cust_type" op="strstr" value="_vip_">
- Same thing matching "vip" case insensitively:
<match:cookie name="cust_type" op="strcasestr" value="_vip_">
-
Special characters
If special characters are included in the value field, they must be embedded in exactly the way the origin server embeds them. For example, the space is considered a special character in cookie values. If the origin server escapes it with %20,
it must be escaped with %20
in the value field. If the origin server doesn't escape it, it should not be escaped. The problem is that browsers don't enforce escaping. How a value appears in the request header really depends on how the origin server created it.
cpcode-range
This match type matches on the content provider code (Billing Code). This match is useful primarily in cases where a content provider has more than one CP code.
The current syntax is:
<match:cpcode-range value="50-55">
</match:cpcode-range>
When the match tag contains ranges, the starting and ending ranges are separated by a dash -
and different ranges are separated by a space. Here's an example:
<match:cpcode-range value="1-101 5381-5500 8000-8999">
</match:cpcode-range>
You can also specify a single number if there's no range:
<match:cpcode-range value="5381 5383 8000-8999 9001">
</match:cpcode-range>
You can specify a range to include all numbers after a particular number by listing an open-ended range, like this:
<match:cpcode-range value="5000-">
arltype
This match type matches on the format of the request ARL. The syntax for this tag is:
<match:arltype value="v1-arl">
Possible values are v1-arl
, transparent
, prepend
.
-
v1-arl
– applies to any ARL that uses Typecodes. These are ARL's used by theThe content delivery network service generally looks like this example:
http://a123.g.akamai.net/7/123/456/e358f5de00e0/www.example.com/lolg.gif
-
prepend
– applies to ARL's that use an ARL token but not a Typecode. The ARL token is generally the same as the hostname in the Absolute URL portion of an ARL. When it is an ARL token, this field can be any string; it doesn't have to conform to the format of a hostname. -
transparent
– is any ARL (actually a URL) that isn't one of the other two. It is called "transparent" because it generally looks like a simple URL. This is the format generally used with edge server configurations.
Example:
The following metadata revalidate any requests that come in the form of a v1-ARL
.
<match:arltype value="v1-arl">
<revalidate>1046581729</revalidate>
</match:arltype>
request-header
This match type matches on the presence of a particular header or the contents of a header in the client request. The syntax for this tag is:
<match:request-header operation=*operation* argument1=*string*
argument2=*string*>
A specific example would be:
<match:request-header operation="name-value-strcasestr" argument1="Referer" argument2=".domain.com">
This request-header tag includes an "operation" to specify what information to look for in the header. The possible values for the operation tag are:
multiple-hosts strstr strcasestr
name-present
name-value-cmp
name-value-casecmp name-value-strstr
name-value-strcasestr regex
Each of these operations is described below with examples.
Negative matching
Each of these match operations can be performed as a "negative match." That is, the match is successful if the conditions specified are not met. The syntax for the negative match is formed by inserting an exclamation mark '!' before the operation name.
Example:
<match:request-header operation="!name-present" header-name="Referer">
This will cause the match to be evaluated to true if the given header name is not present.
Special case for name value matches
There's a special rule for the "name-value" functions for cases where the given header name occurs multiple times in the request header. If the function is not being negated, the match will evaluate to true if the given header value matches the value of any of the headers. If the function is being negated, the match will only evaluate to true if none of the values of the incoming header match the one specified in meta- data.
multiple-hosts
Matches requests whose header contains more than one Host header.
<match:request-header operation="multiple-hosts">
For operation="multiple-hosts"
, argument1
and argument2
are ignored and can be left out or included without affecting edge server behavior.
!multiple-hosts matches if the request has no Host header or has just one Host header.
strstr
This match value requires an argument1
property, which is a substring to match anywhere in the entire request headers. The match is case sensitive.
<match:request-header operation="strstr" argument1="abc">
argument2
is ignored and can be left out or included without affecting edge server behavior.
!strstr matches if the given substring is not in the header.
strcasestr
Same as strstr except that it's not case sensitive.
<match:request-header operation="strcasestr" argument1="abc">
argument2
is ignored and can be left out or included without affecting edge server behavior.
!strcasestr matches if the given substring is not in the header. The match is not case sensitive.
name-present
This operation matches requests that contain the given request header. This match is not case sensitive. argument1
specifies the header name.
<match:request-header operation="name-present" argument1="Referer">
argument2
is ignored and can be left out or included without affecting edge server behavior.
!name-present matches if the given header name is not part of the request headers.
name-value-cmp
Matches requests where a request header with a specified name (argument1
) matches the given header-value (argument2
). The match must be exact, rather than a substring of the header value. The match is case sensitive.
<match:request-header operation="name-value-cmp" argument1="User-Agent" argument2="Custom Agent">
!name-value-cmp matches if either the given header name is not present or its value doesn't match the one specified in metadata.
name-value-casecmp
This match functions like name-value-cmp
except that the match is not case sensitive.
<match:request-header operation="name-value-casecmp" argument1="user- agent" argument2="custom-agent">
!name-value-casecmp matches if either the given header name is not present or its value doesn't match the one specified in metadata. The match is not case sensitive.
name-value-strstr
This operation matches requests where the specified header (argument1
) contains the given substring (argument2
) somewhere in its value. The match is case sensitive.
<match:request-header operation="name-value-strstr" argument1="Referer" argument2=".domain.com">
!name-value-strstr matches if either the given header name is not present or the substring specified in metadata is not part of the header's value.
name-value-strcasestr
Same as name-value-strstr above except that the match is not case sensitive.
<match:request-header operation="name-value-strcasestr" argument1="Referer" argument2=".domain.com">
!name-value-strcasestr matches if either the given header name is not present or the substring specified in metadata is not part of the header's value. The match is not case-sensitive.
regex
Matches on a regular expression pattern using extended regular expressions
Example:
<match:request-header operation="regex" argument1="ab[cd]">
request-type
This matches on the type of request the edge server receives. Possible values for the tag are: user
, esi-fragment
, esi-war
, and esi-tunnel
.
<match:request-type value="esi-fragment">
</match:request-type>
esi-fragment
matches on fragment requests going from ESI->edge server->origin and back from origin->edge server->ESI.
esi-war
matches on WAR requests going from ESI->edge server->origin and back from origin->edge server->ESI.
esi-tunnel
matches on request-mod (EdgeJava) requests going from ESI->edge server->ej-tomcat and back from ej-tomcat->edge server->user. It's used to forward requests to the local Java app server. This is the only request-type that's not applicable to cache since all request-mod requests go to the local Java app server.
user
matches everything else. This maintains backward compatibility with the esi-fragment match type, which matched on whether a request was for a fragment, or not for a fragment. User registers a positive match if the request is not any of the other types (esi-fragment
, esi-war
, esi-tunnel
).
The edge server allows multiple values for the request-type match with a comma separator to indicate that the match should evaluate to true if any of the request types match, for example:
<match:request-type value="user,esi-tunnel,esi-war">
The old match type <match:esi-fragment value="on|off ">
was adjusted for backward compatibility so that the on
setting is the same as <match:request-type value="esi- fragment">
and the off
setting is the same as <match:request-type value="user">
.
method
This match type allows for application of metadata based on the method used in the request (GET
, POST
, HEAD
and any others recognized by the edge servers). Method is a component of the cache key by default. This is useful if for example POST
responses are being cached and you want to distinguish between POST
and GET
in your invalidation request. The match is case insensitive.
<match:method value="pOsT">
<revalidate>1046581729</revalidate>
</match:method>
protocol
This tag matches on the protocol used in the incoming request.
<match:protocol value="HTTPS">
<revalidate>1046581729</revalidate>
</match:protocol>
Acceptable values are HTTPS
or HTTP
. When the client connects through SSL HTTPS produces a match, otherwise HTTP
is a match.
query-string
This tag matches on an argument in the query string with functionality similar to what is available for matching on cookies. Useful if query arguments are being used to distinguish objects in cache by including the arguments in the cache key. The tag can match for whether the query string argument:
-
is either present or missing
-
has or doesn't have a particular value
-
has or doesn't have a particular substring inside it
The matching functions can be specified as either case sensitive or case insensitive. The metadata tag is:
<match:query-string name="*arg-name*" name-prefix-match="*off*" op="*operation-type*">
The properties are as follows:
-
name: Contains the name of the argument in the query string to match against. The edge server looks for this name in the query string using a case sensitive match.
-
name-prefix-match: This is a flag that indicates whether the parameter name given (above) is just a prefix. The default is
off
. -
op: Indicates the match operation to perform. It has to be one of the following five values. Each of these can be testing for the negative by preceding the op name with an exclamation point (for example,
"!name-present"
). -
name-present: To check whether given parameter name is present
strcmp
- the given parameter contains the given value.strcasecmp
- same as strcmp but not case sensitive. -
strstr: The given parameter contains the given substring.
-
strcasestr: Same as strstr but not case sensitive.wildcard: case sensitive match where
*
represents zero or more characters and?
represents one character. -
wildcardcase: Same as wildcard but not case sensitive.
-
value: Contains the value/substring to match against. If you want to match against the absence of a value, the edge server will accept
value=""
and perform the match correctly. However, in version 4.3, MUI will not permit this syntax, so you need to enter it by hand. This limitation will be addressed in version 4.4). -
unescape: Indicates how to unescape the query parameter's value before the match operation.
-
none: The query string value will be compared as is (this is the default).
-
url-unescape: The query string value will be url unescaped before the comparison.
Examples:
- Check whether the
sessionid
query string parameter is present:
<match:query-string op="name-present" name="sessionid">
- Check whether the
sessionid
query string parameter is missing:
<match:query-string op="!name-present" name="sessionid">
- Check whether the
account
query string parameter contains the valuevalid
(case insensitively):
<match:query-string op="strcasecmp" name="account" value="valid">
- Check whether the
account
query string parameter contains a value other thanvalid
(case sensitively):
<match:query-string op="!strcmp" name="account" value="valid">
- Check whether the
product_name
query string parameter contains the wordcomputer
anywhere inside it (case sensitively):
<match:query-string op="strstr" name="product_name" value="computer">
- Check whether the
product_name
query string parameter doesn't contain the wordcomputer
(case sensitively):
<match:query-string op="!strstr" name="product_name" value="computer">
typecode
Matches on the typecode of the request v1 ARL. The value of the tag is a space-separated list of typecode characters. May be useful if you want to invalidate request objects that use a particular typecode. For example, all requests that use an Object ID under typecode 7
.
<match:typecode value="5 7">
...
</match:typecode>
Updated 6 months ago