Share via

Rules Engines - Create Or Update

Service:
Front Door Service
API Version:
2021-06-01

Creates a new Rules Engine Configuration with the specified name within the specified Front Door.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/frontDoors/{frontDoorName}/rulesEngines/{rulesEngineName}?api-version=2021-06-01

URI Parameters

Name In Required Type Description
frontDoorName
 path True

string

minLength: 5
maxLength: 64
pattern: ^[a-zA-Z0-9]+([-a-zA-Z0-9]?[a-zA-Z0-9])*$

Name of the Front Door which is globally unique.
resourceGroupName
 path True

string

minLength: 1
maxLength: 80
pattern: ^[a-zA-Z0-9_\-\(\)\.]*[^\.]$

Name of the Resource group within the Azure subscription.
rulesEngineName
 path True

string

minLength: 1
maxLength: 90
pattern: ^[a-zA-Z0-9]+(-*[a-zA-Z0-9])*$

Name of the Rules Engine which is unique within the Front Door.
subscriptionId
 path True

string

The subscription credentials which uniquely identify the Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.
api-version
 query True

string

Client API version.

Request Body

Name Type Description
properties.rules

RulesEngineRule[]

A list of rules that define a particular Rules Engine Configuration.

Responses

Name Type Description
200 OK

RulesEngine

OK
201 Created

RulesEngine

Created
202 Accepted

RulesEngine

Accepted
Other Status Codes

ErrorResponse

Front Door error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create or update a specific Rules Engine Configuration

Sample request

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/frontDoors/frontDoor1/rulesEngines/rulesEngine1?api-version=2021-06-01

{
  "properties": {
    "rules": [
      {
        "name": "Rule1",
        "priority": 1,
        "action": {
          "routeConfigurationOverride": {
            "@odata.type": "#Microsoft.Azure.FrontDoor.Models.FrontdoorRedirectConfiguration",
            "redirectType": "Moved",
            "redirectProtocol": "HttpsOnly",
            "customHost": "www.bing.com",
            "customPath": "/api",
            "customFragment": "fragment",
            "customQueryString": "a=b"
          }
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RemoteAddr",
            "rulesEngineOperator": "GeoMatch",
            "rulesEngineMatchValue": [
              "CH"
            ]
          }
        ],
        "matchProcessingBehavior": "Stop"
      },
      {
        "name": "Rule2",
        "priority": 2,
        "action": {
          "responseHeaderActions": [
            {
              "headerActionType": "Overwrite",
              "headerName": "Cache-Control",
              "value": "public, max-age=31536000"
            }
          ]
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RequestFilenameExtension",
            "rulesEngineOperator": "Equal",
            "rulesEngineMatchValue": [
              "jpg"
            ],
            "transforms": [
              "Lowercase"
            ]
          }
        ]
      },
      {
        "name": "Rule3",
        "priority": 3,
        "action": {
          "routeConfigurationOverride": {
            "@odata.type": "#Microsoft.Azure.FrontDoor.Models.FrontdoorForwardingConfiguration",
            "customForwardingPath": null,
            "forwardingProtocol": "HttpsOnly",
            "cacheConfiguration": {
              "queryParameterStripDirective": "StripOnly",
              "queryParameters": "a=b,p=q",
              "dynamicCompression": "Disabled",
              "cacheDuration": "P1DT12H20M30S"
            },
            "backendPool": {
              "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/frontDoors/frontDoor1/backendPools/backendPool1"
            }
          }
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RequestHeader",
            "rulesEngineOperator": "Equal",
            "rulesEngineMatchValue": [
              "allowoverride"
            ],
            "transforms": [
              "Lowercase"
            ],
            "negateCondition": false,
            "selector": "Rules-Engine-Route-Forward"
          }
        ]
      }
    ]
  }
}

Sample response

Status code:
200 
{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/frontDoors/frontDoor1/rulesEngines/rulesEngine1",
  "name": "rulesEngine1",
  "properties": {
    "rules": [
      {
        "name": "Rule1",
        "priority": 1,
        "action": {
          "routeConfigurationOverride": {
            "@odata.type": "#Microsoft.Azure.FrontDoor.Models.FrontdoorRedirectConfiguration",
            "redirectType": "Moved",
            "redirectProtocol": "HttpsOnly",
            "customHost": "www.bing.com",
            "customPath": "/api",
            "customFragment": "fragment",
            "customQueryString": "a=b"
          }
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RemoteAddr",
            "rulesEngineOperator": "GeoMatch",
            "rulesEngineMatchValue": [
              "CH"
            ]
          }
        ],
        "matchProcessingBehavior": "Stop"
      },
      {
        "name": "Rule2",
        "priority": 2,
        "action": {
          "responseHeaderActions": [
            {
              "headerActionType": "Overwrite",
              "headerName": "Cache-Control",
              "value": "public, max-age=31536000"
            }
          ]
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RequestFilenameExtension",
            "rulesEngineOperator": "Equal",
            "rulesEngineMatchValue": [
              "jpg"
            ],
            "transforms": [
              "Lowercase"
            ]
          }
        ]
      }
    ]
  }
}
Status code:
201 
{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/frontDoors/frontDoor1/rulesEngines/rulesEngine1",
  "name": "rulesEngine1",
  "properties": {
    "rules": [
      {
        "name": "Rule1",
        "priority": 1,
        "action": {
          "routeConfigurationOverride": {
            "@odata.type": "#Microsoft.Azure.FrontDoor.Models.FrontdoorRedirectConfiguration",
            "redirectType": "Moved",
            "redirectProtocol": "HttpsOnly",
            "customHost": "www.bing.com",
            "customPath": "/api",
            "customFragment": "fragment",
            "customQueryString": "a=b"
          }
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RemoteAddr",
            "rulesEngineOperator": "GeoMatch",
            "rulesEngineMatchValue": [
              "CH"
            ]
          }
        ],
        "matchProcessingBehavior": "Stop"
      },
      {
        "name": "Rule2",
        "priority": 2,
        "action": {
          "responseHeaderActions": [
            {
              "headerActionType": "Overwrite",
              "headerName": "Cache-Control",
              "value": "public, max-age=31536000"
            }
          ]
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RequestFilenameExtension",
            "rulesEngineOperator": "Equal",
            "rulesEngineMatchValue": [
              "jpg"
            ],
            "transforms": [
              "Lowercase"
            ]
          }
        ]
      }
    ]
  }
}
Status code:
202 
{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/frontDoors/frontDoor1/rulesEngines/rulesEngine1",
  "name": "rulesEngine1",
  "properties": {
    "rules": [
      {
        "name": "Rule1",
        "priority": 1,
        "action": {
          "routeConfigurationOverride": {
            "@odata.type": "#Microsoft.Azure.FrontDoor.Models.FrontdoorRedirectConfiguration",
            "redirectType": "Moved",
            "redirectProtocol": "HttpsOnly",
            "customHost": "www.bing.com",
            "customPath": "/api",
            "customFragment": "fragment",
            "customQueryString": "a=b"
          }
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "RemoteAddr",
            "rulesEngineOperator": "GeoMatch",
            "rulesEngineMatchValue": [
              "CH"
            ]
          }
        ],
        "matchProcessingBehavior": "Stop"
      },
      {
        "name": "Rule2",
        "priority": 2,
        "action": {
          "responseHeaderActions": [
            {
              "headerActionType": "Overwrite",
              "headerName": "Cache-Control",
              "value": "public, max-age=31536000"
            }
          ]
        },
        "matchConditions": [
          {
            "rulesEngineMatchVariable": "FilenameExtension",
            "rulesEngineOperator": "Equal",
            "rulesEngineMatchValue": [
              "jpg"
            ],
            "transforms": [
              "Lowercase"
            ]
          }
        ]
      }
    ]
  }
}

Definitions

Name Description
CacheConfiguration

Caching settings for a caching-type route. To disable caching, do not provide a cacheConfiguration object.
DynamicCompressionEnabled

Whether to use dynamic compression for cached content
ErrorResponse

Error response indicates Front Door service is not able to process the incoming request. The reason is provided in the error message.
ForwardingConfiguration

Describes Forwarding Route.
FrontDoorForwardingProtocol

Protocol this rule will use when forwarding traffic to backends.
FrontDoorQuery

Treatment of URL query terms when forming the cache key.
FrontDoorRedirectProtocol

The protocol of the destination to where the traffic is redirected
FrontDoorRedirectType

The redirect type the rule will use when redirecting traffic.
FrontDoorResourceState

Resource status of the Front Door or Front Door SubResource.
HeaderAction

An action that can manipulate an http header.
headerActionType

Which type of manipulation to apply to the header.
MatchProcessingBehavior

If this rule is a match should the rules engine continue running the remaining rules or stop. If not present, defaults to Continue.
RedirectConfiguration

Describes Redirect Route.
RulesEngine

A rules engine configuration containing a list of rules that will run to modify the runtime behavior of the request and response.
RulesEngineAction

One or more actions that will execute, modifying the request and/or response.
RulesEngineMatchCondition

Define a match condition
RulesEngineMatchVariable

Match Variable
RulesEngineOperator

Describes operator to apply to the match condition.
RulesEngineRule

Contains a list of match conditions, and an action on how to modify the request/response. If multiple rules match, the actions from one rule that conflict with a previous rule overwrite for a singular action, or append in the case of headers manipulation.
SubResource

Reference to another subresource.
transform

Describes what transforms are applied before matching

CacheConfiguration

Object

Caching settings for a caching-type route. To disable caching, do not provide a cacheConfiguration object.

Name Type Description
cacheDuration

string (duration)

The duration for which the content needs to be cached. Allowed format is in ISO 8601 format (http://en.wikipedia.org/wiki/ISO_8601#Durations). HTTP requires the value to be no more than a year
dynamicCompression

DynamicCompressionEnabled

Whether to use dynamic compression for cached content
queryParameterStripDirective

FrontDoorQuery

Treatment of URL query terms when forming the cache key.
queryParameters

string

query parameters to include or exclude (comma separated).

DynamicCompressionEnabled

Enumeration

Whether to use dynamic compression for cached content

Value Description
Enabled
Disabled

ErrorResponse

Object

Error response indicates Front Door service is not able to process the incoming request. The reason is provided in the error message.

Name Type Description
code

string

Error code.
message

string

Error message indicating why the operation failed.

ForwardingConfiguration

Object

Describes Forwarding Route.

Name Type Description
@odata.type string:

#Microsoft.Azure.FrontDoor.Models.FrontdoorForwardingConfiguration

backendPool

SubResource

A reference to the BackendPool which this rule routes to.
cacheConfiguration

CacheConfiguration

The caching configuration associated with this rule.
customForwardingPath

string

A custom path used to rewrite resource paths matched by this rule. Leave empty to use incoming path.
forwardingProtocol

FrontDoorForwardingProtocol

Protocol this rule will use when forwarding traffic to backends.

FrontDoorForwardingProtocol

Enumeration

Protocol this rule will use when forwarding traffic to backends.

Value Description
HttpOnly
HttpsOnly
MatchRequest

FrontDoorQuery

Enumeration

Treatment of URL query terms when forming the cache key.

Value Description
StripNone
StripAll
StripOnly
StripAllExcept

FrontDoorRedirectProtocol

Enumeration

The protocol of the destination to where the traffic is redirected

Value Description
HttpOnly
HttpsOnly
MatchRequest

FrontDoorRedirectType

Enumeration

The redirect type the rule will use when redirecting traffic.

Value Description
Moved
Found
TemporaryRedirect
PermanentRedirect

FrontDoorResourceState

Enumeration

Resource status of the Front Door or Front Door SubResource.

Value Description
Creating
Enabling
Enabled
Disabling
Disabled
Deleting
Migrating
Migrated

HeaderAction

Object

An action that can manipulate an http header.

Name Type Description
headerActionType

headerActionType

Which type of manipulation to apply to the header.
headerName

string

The name of the header this action will apply to.
value

string

The value to update the given header name with. This value is not used if the actionType is Delete.

headerActionType

Enumeration

Which type of manipulation to apply to the header.

Value Description
Append
Delete
Overwrite

MatchProcessingBehavior

Enumeration

If this rule is a match should the rules engine continue running the remaining rules or stop. If not present, defaults to Continue.

Value Description
Continue
Stop

RedirectConfiguration

Object

Describes Redirect Route.

Name Type Description
@odata.type string:

#Microsoft.Azure.FrontDoor.Models.FrontdoorRedirectConfiguration

customFragment

string

Fragment to add to the redirect URL. Fragment is the part of the URL that comes after #. Do not include the #.
customHost

string

Host to redirect. Leave empty to use the incoming host as the destination host.
customPath

string

The full path to redirect. Path cannot be empty and must start with /. Leave empty to use the incoming path as destination path.
customQueryString

string

The set of query strings to be placed in the redirect URL. Setting this value would replace any existing query string; leave empty to preserve the incoming query string. Query string must be in <key>=<value> format. The first ? and & will be added automatically so do not include them in the front, but do separate multiple query strings with &.
redirectProtocol

FrontDoorRedirectProtocol

The protocol of the destination to where the traffic is redirected
redirectType

FrontDoorRedirectType

The redirect type the rule will use when redirecting traffic.

RulesEngine

Object

A rules engine configuration containing a list of rules that will run to modify the runtime behavior of the request and response.

Name Type Description
id

string

Resource ID.
name

string

Resource name.
properties.resourceState

FrontDoorResourceState

Resource status of the Front Door or Front Door SubResource.
Resource status.
properties.rules

RulesEngineRule[]

A list of rules that define a particular Rules Engine Configuration.
type

string

Resource type.

RulesEngineAction

Object

One or more actions that will execute, modifying the request and/or response.

Name Type Description
requestHeaderActions

HeaderAction[]

A list of header actions to apply from the request from AFD to the origin.
responseHeaderActions

HeaderAction[]

A list of header actions to apply from the response from AFD to the client.
routeConfigurationOverride RouteConfiguration:

Override the route configuration.

RulesEngineMatchCondition

Object

Define a match condition

Name Type Description
negateCondition

boolean

Describes if this is negate condition or not
rulesEngineMatchValue

string[]

Match values to match against. The operator will apply to each value in here with OR semantics. If any of them match the variable with the given operator this match condition is considered a match.
rulesEngineMatchVariable

RulesEngineMatchVariable

Match Variable
rulesEngineOperator

RulesEngineOperator

Describes operator to apply to the match condition.
selector

string

Name of selector in RequestHeader or RequestBody to be matched
transforms

transform[]

List of transforms

RulesEngineMatchVariable

Enumeration

Match Variable

Value Description
IsMobile
RemoteAddr
RequestMethod
QueryString
PostArgs
RequestUri
RequestPath
RequestFilename
RequestFilenameExtension
RequestHeader
RequestBody
RequestScheme

RulesEngineOperator

Enumeration

Describes operator to apply to the match condition.

Value Description
Any
IPMatch
GeoMatch
Equal
Contains
LessThan
GreaterThan
LessThanOrEqual
GreaterThanOrEqual
BeginsWith
EndsWith

RulesEngineRule

Object

Contains a list of match conditions, and an action on how to modify the request/response. If multiple rules match, the actions from one rule that conflict with a previous rule overwrite for a singular action, or append in the case of headers manipulation.

Name Type Description
action

RulesEngineAction

Actions to perform on the request and response if all of the match conditions are met.
matchConditions

RulesEngineMatchCondition[]

A list of match conditions that must meet in order for the actions of this rule to run. Having no match conditions means the actions will always run.
matchProcessingBehavior

MatchProcessingBehavior

If this rule is a match should the rules engine continue running the remaining rules or stop. If not present, defaults to Continue.
name

string

A name to refer to this specific rule.
priority

integer

A priority assigned to this rule.

SubResource

Object

Reference to another subresource.

Name Type Description
id

string

Resource ID.

transform

Enumeration

Describes what transforms are applied before matching

Value Description
Lowercase
Uppercase
Trim
UrlDecode
UrlEncode
RemoveNulls