Guide
TrainingSupportCommunity

Request matches

Suggest Edits

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 and xxsessionid but not sessionidyy or xxsession- idyy.

    • sessionid* matches: sessionid and sessionidyy but not xxsessionid or xxsession- idyy.

    • * matches all cookie names.

    • *a*a*a* matches a cookie name that has three letters a 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 the

    The 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 value valid (case insensitively):
<match:query-string op="strcasecmp" name="account" value="valid">
  • Check whether the account query string parameter contains a value other than valid (case sensitively):
<match:query-string op="!strcmp" name="account" value="valid">
  • Check whether the product_name query string parameter contains the word computer 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 word computer (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 9 months ago