Once a Cloudlet policy has been created, you can add match rules to a version of that policy.
The maximum number of rules per Cloudlets policy is currently 5,000. However, there is no limit to the number of Cloudlets policies you can create.
Working with match rules
When working with Cloudlets match rules, all of the match criteria are included in the matchRules array.
Within the matchRules array, it is common to use the matches array, which defines potential conditions, like case sensitivity (caseSensitive) or the type of match (matchType). These properties apply to all Cloudlets.
You use the matchType properties to set up the part of the request that the rule applies to, like redirect URL (matchURL) or path and query string (pathAndQS).
For additional examples, see Cloudlet-specific match examples.
When a Cloudlet executes, the first rule applied is the first one that is true based on criteria in the incoming request.
Match rule considerations
When setting up rules for Cloudlets, be aware of the following:
- There is currently no way to implement an else case in a rule.
- There are no child rules within Cloudlet policies.
- When a new policy is created, version 1 of the policy is also created. This version is empty: it contains neither a description nor any match rules (
matchRules). - If you clone an existing policy, the
matchRulesfor version 1 of the new policy are copied from the most recent version of the cloned policy.
Match rule versions
When setting up the rules for a Cloudlet policy version, you first need to determine the matchRuleFormat to use. The matchRuleFormat attribute indicates the version of the Cloudlet-specific matchRules JSON, and uses the following format: {major}.{minor}. The major number always matches the value in the URI pathname (.../api/{version}/...). The current major version is 3. The minor number changes as attributes are added to or removed from the resource objects.
If you issue a PUT or POST request for Cloudlet policy versions that include
matchRules, you also need to use thematchRuleFormatproperty.
Match with wildcards
You can use wildcard characters (* and ?) for the following match types: cookie, header, path, extension, query, and hostname.
The
cookieandquerymatches only accept wildcards for the value, not the cookie or query name. For example,"matchValue":"cookiename=m*nster"would be valid, but"matchValue":"c*kiename=m*nster"would not.
As a wildcard, the asterisk represents zero or more characters in a string of characters, and the question mark represents a single character.
With the exception of hostname, when using a wildcard with this API, you need to set the matchOperator parameter to contains. For hostname, the contains setting is not required. If you enter an asterisk in the hostname property, it is automatically treated as a wildcard.
Wildcard match example
In the following example, the first match listed uses a wildcard: the matchvalue of /products/wildcards/*.jpg matches on any .jpg file in the /products/wildcards/ directory. This is because the matchOperator is contains.
The second match, however, literally looks for a file called *.jpg because the matchOperator is equals.
{
"matchRules": [
{
"matchURL": null,
"start": 0,
"end": 0,
"type": "apMatchRule",
"useIncomingQueryString": false,
"passThroughPercent": "50",
"name": "RequiredNameField",
"id": null,
"matches": [
{
"matchType": "path",
"matchValue": "/products/wildcards/*.jpg",
"matchOperator": "contains",
"negate": false,
"caseSensitive": false
},
{
"matchType": "path",
"matchValue": "/products/literals/*.jpg",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
]
}
]
}
Match with regular expressions
For the Audience Segmentation, Edge Redirector, and Forward Rewrite Cloudlets, you can now use regular expressions to match on the fully qualified incoming request URL.
The regular expression can be up to 256 characters. If your regular expression includes any characters that have a special use in regular expressions (like ., +, or ?), you must use a backslash (\) to escape each special character.
For Cloudlets, RE2 is supported. RE2 is a library for regular expressions with a C++ interface that uses the finite-state machine (FSM) computational model. Go to Google's re2 repository or a similar site, for information about RE2's syntax.
For Edge Redirector, you can also use the information from capture groups in regular expressions to form the redirect URL. For Audience Segmentation and Forward Rewrite you can use the information from capture groups in regular expressions to form the forward path and, if desired, the query string.
Capture groups allow you to capture incoming information from the source URL, while substitution patterns allow you to refer to those capture groups in the modified URL. Substitution patterns use the backslash character (\) followed by a number to refer to the capture groups. For example, \1 is the first capture group, \2 is the second, etc.
The regular expressions match for Cloudlets supports a maximum of nine numbered substitutions using capture groups.
Regular expression match example
The following is an example of a Forward Rewrite match rule that contains a regular expression.
{
"matchRules": [
{
"matches": [
{
"matchType": "regex",
"matchValue": "^https?://(?:[A-z0-9|\\.]*)/(.*)",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
"start": 0,
"end": 0,
"type": "frMatchRule",
"forwardSettings": {
"pathAndQS": "/\\1&extra_param=bar",
"useIncomingQueryString": false
},
"id": null
}
],
"matchRuleFormat": "1.0",
"rulesLocked": false
}
In this example, the regular expression value is ^https?://(?:[A-z0-9|\.]*)/(.*) and the forward path and query string value containing a substitution pattern is /\1&extra_param=bar. When this rule is activated, all requests to http://www.example.com/path1/path2/home.html?query=foo would retrieve content from http://www.example.com/path1/path2/home.html? query=foo&extra_param=bar without changing the URL.
Match types that support multiple values
The following matchType properties support multiple space-separated values (not names): extension, hostname, path, and query. When setting up a rule using these match types, you can accidentally create a rule that never matches a request, like the following:
JSON
"matches": [
{
"matchType": "query",
"matchValue": "p=x",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
{
"matchType": "query",
"matchValue": "p=y",
"matchOperator": "equals",
"negate": false,
"caseSensitive": false
}
],
The separate match conditions in this example do not work because the incoming request has to have both p=x and p=y, which is not valid. However, if matchValue:"p=x y", it means a match occurs if either p=x or p=y is in the incoming request.
Matches in requests and responses
When adding match rule criteria to the JSON request for a POST or PUT operation on the /policies/{nnnn}/versions/{n} endpoint, you set up the matchRules array after defining the matchRuleFormat. Here, for example, is a PUT request that adds an Edge Redirector rule with matches based on the incoming request header:
{
"description" : "Edge Redirector Header Rules",
"matchRuleFormat" : "1.0",
"matchRules" : [
{
"type": "erMatchRule",
"end": 1403127780,
"id": 0,
"matches": [
{
"matchOperator": "contains",
"matchType": "header",
"objectMatchValue": {
"type": "object",
"name": "contentType",
"nameCaseSensitive": false,
"nameHasWildcard": false,
"options": {
"value": [
"text/html*",
"text/css*",
"application/x-javascript*"
],
"valueHasWildcard": true,
"valueCaseSensitive": false
}
}
},
{
"matchOperator": "exists",
"matchType": "header",
"objectMatchValue": {
"type": "object",
"name": "Cache-Control",
"nameCaseSensitive": false,
"nameHasWildcard": false
},
"negate": false
}
],
"name": rule1,
"redirectURL": "http://www.redirect.com",
"start": 1403041407,
"statusCode": 301,
"useIncomingQueryString": false
}
The response includes the same match information you provided in the request.