Policy Restrictions - Check At Resource Group Scope

  • Reference
Service:
Policy
API Version:
2023-03-01

Checks what restrictions Azure Policy will place on a resource within a resource group. Use this when the resource group the resource will be created in is already known.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/checkPolicyRestrictions?api-version=2023-03-01

URI Parameters

Name In Required Type Description
resourceGroupName
 path True

string

The name of the resource group. The name is case insensitive.
subscriptionId
 path True

string

The ID of the target subscription.
api-version
 query True

string

The API version to use for this operation.

Request Body

Name Required Type Description
resourceDetails True

CheckRestrictionsResourceDetails

The information about the resource that will be evaluated.
includeAuditEffect

boolean

Whether to include policies with the 'audit' effect in the results. Defaults to false.
pendingFields

PendingField[]

The list of fields and values that should be evaluated for potential restrictions.

Responses

Name Type Description
200 OK

CheckRestrictionsResult

The restrictions that will be placed on the resource by Azure Policy.
Other Status Codes

ErrorResponse

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

Check policy restrictions at resource group scope
Check policy restrictions at resource group scope including audit effect

Check policy restrictions at resource group scope

Sample request

POST https://management.azure.com/subscriptions/35ee058e-5fa0-414c-8145-3ebb8d09b6e2/resourceGroups/vmRg/providers/Microsoft.PolicyInsights/checkPolicyRestrictions?api-version=2023-03-01

{
  "resourceDetails": {
    "resourceContent": {
      "type": "Microsoft.Compute/virtualMachines",
      "properties": {
        "priority": "Spot"
      }
    },
    "apiVersion": "2019-12-01"
  },
  "pendingFields": [
    {
      "field": "name",
      "values": [
        "myVMName"
      ]
    },
    {
      "field": "location",
      "values": [
        "eastus",
        "westus",
        "westus2",
        "westeurope"
      ]
    },
    {
      "field": "tags"
    }
  ]
}

Sample response

Status code:
200 
{
  "fieldRestrictions": [
    {
      "field": "tags.newtag",
      "restrictions": [
        {
          "result": "Required",
          "defaultValue": "defaultVal",
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/1D0906C3",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/57DAC8A0",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/05D92080",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Deny",
          "reason": "tags.newtag is required"
        }
      ]
    },
    {
      "field": "tags.environment",
      "restrictions": [
        {
          "result": "Required",
          "values": [
            "Prod",
            "Int",
            "Test"
          ],
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/30BD79F6",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/7EB1508A",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/735551F1",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Deny",
          "reason": "tags.environment is required"
        }
      ]
    },
    {
      "field": "location",
      "restrictions": [
        {
          "result": "Deny",
          "values": [
            "west europe"
          ],
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/0711CCC1",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/1563EBD3",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/1E17783A",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Deny",
          "reason": "location must be one of the following: eastus, westus, westus2"
        },
        {
          "result": "Deny",
          "values": [
            "eastus",
            "westus"
          ],
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/25C9F66B",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/5382A69D",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/392D107B",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Deny",
          "reason": "location must be one of the following: westus2"
        }
      ]
    }
  ],
  "contentEvaluationResult": {
    "policyEvaluations": [
      {
        "policyInfo": {
          "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/435CAE41",
          "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/2162358E",
          "policyDefinitionReferenceId": "defref222",
          "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/2FF66C37"
        },
        "evaluationResult": "NonCompliant",
        "evaluationDetails": {
          "evaluatedExpressions": [
            {
              "result": "True",
              "expressionKind": "field",
              "expression": "type",
              "path": "type",
              "expressionValue": "microsoft.compute/virtualmachines",
              "targetValue": "microsoft.compute/virtualmachines",
              "operator": "equals"
            }
          ]
        },
        "effectDetails": {
          "policyEffect": "Deny"
        }
      }
    ]
  }
}

Check policy restrictions at resource group scope including audit effect

Sample request

POST https://management.azure.com/subscriptions/35ee058e-5fa0-414c-8145-3ebb8d09b6e2/resourceGroups/vmRg/providers/Microsoft.PolicyInsights/checkPolicyRestrictions?api-version=2023-03-01

{
  "resourceDetails": {
    "resourceContent": {
      "type": "Microsoft.Compute/virtualMachines",
      "properties": {
        "priority": "Spot"
      }
    },
    "apiVersion": "2019-12-01"
  },
  "pendingFields": [
    {
      "field": "name",
      "values": [
        "myVMName"
      ]
    },
    {
      "field": "location",
      "values": [
        "eastus",
        "westus",
        "westus2",
        "westeurope"
      ]
    },
    {
      "field": "tags"
    }
  ],
  "includeAuditEffect": true
}

Sample response

Status code:
200 
{
  "fieldRestrictions": [
    {
      "field": "tags.newtag",
      "restrictions": [
        {
          "result": "Required",
          "defaultValue": "defaultVal",
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/1D0906C3",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/57DAC8A0",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/05D92080",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Deny",
          "reason": "tags.newtag is required"
        }
      ]
    },
    {
      "field": "tags.environment",
      "restrictions": [
        {
          "result": "Required",
          "values": [
            "Prod",
            "Int",
            "Test"
          ],
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/30BD79F6",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/7EB1508A",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/735551F1",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Audit",
          "reason": "tags.environment is required"
        }
      ]
    },
    {
      "field": "location",
      "restrictions": [
        {
          "result": "Deny",
          "values": [
            "west europe"
          ],
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/0711CCC1",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/1563EBD3",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/1E17783A",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Deny",
          "reason": "The selected location is not allowed"
        },
        {
          "result": "Audit",
          "values": [
            "eastus",
            "westus"
          ],
          "policy": {
            "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/25C9F66B",
            "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/5382A69D",
            "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/392D107B",
            "policyDefinitionReferenceId": "DefRef"
          },
          "policyEffect": "Audit",
          "reason": "The selected location is not allowed"
        }
      ]
    }
  ],
  "contentEvaluationResult": {
    "policyEvaluations": [
      {
        "policyInfo": {
          "policyDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyDefinitions/435CAE41",
          "policySetDefinitionId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policySetDefinitions/2162358E",
          "policyDefinitionReferenceId": "defref222",
          "policyAssignmentId": "/subscriptions/d8db6de6-2b96-46af-b825-07aef2033c0b/providers/microsoft.authorization/policyAssignments/2FF66C37"
        },
        "evaluationResult": "NonCompliant",
        "evaluationDetails": {
          "evaluatedExpressions": [
            {
              "result": "True",
              "expressionKind": "field",
              "expression": "type",
              "path": "type",
              "expressionValue": "microsoft.compute/virtualmachines",
              "targetValue": "microsoft.compute/virtualmachines",
              "operator": "equals"
            }
          ],
          "reason": "Resource creation of the selected type is not allowed"
        },
        "effectDetails": {
          "policyEffect": "Audit"
        }
      }
    ]
  }
}

Definitions

Name Description
CheckRestrictionEvaluationDetails

Policy evaluation details.
CheckRestrictionsRequest

The check policy restrictions parameters describing the resource that is being evaluated.
CheckRestrictionsResourceDetails

The information about the resource that will be evaluated.
CheckRestrictionsResult

The result of a check policy restrictions evaluation on a resource.
ContentEvaluationResult

Evaluation results for the provided partial resource content.
ErrorDefinition

Error definition.
ErrorResponse

Error response.
ExpressionEvaluationDetails

Evaluation details of policy language expressions.
FieldRestriction

The restrictions on a field imposed by a specific policy.
FieldRestrictionResult

The type of restriction that is imposed on the field.
FieldRestrictions

The restrictions that will be placed on a field in the resource by policy.
IfNotExistsEvaluationDetails

Evaluation details of IfNotExists effect.
PendingField

A field that should be evaluated against Azure Policy to determine restrictions.
PolicyEffectDetails

The details of the effect that was applied to the resource.
PolicyEvaluationResult

The result of a non-compliant policy evaluation against the given resource content.
PolicyReference

Resource identifiers for a policy.
TypedErrorInfo

Scenario specific error details.

CheckRestrictionEvaluationDetails

Policy evaluation details.

Name Type Description
evaluatedExpressions

ExpressionEvaluationDetails[]

Details of the evaluated expressions.
ifNotExistsDetails

IfNotExistsEvaluationDetails

Evaluation details of IfNotExists effect.
reason

string

The reason for the evaluation result.

CheckRestrictionsRequest

The check policy restrictions parameters describing the resource that is being evaluated.

Name Type Default value Description
includeAuditEffect

boolean

False

Whether to include policies with the 'audit' effect in the results. Defaults to false.
pendingFields

PendingField[]

The list of fields and values that should be evaluated for potential restrictions.
resourceDetails

CheckRestrictionsResourceDetails

The information about the resource that will be evaluated.

CheckRestrictionsResourceDetails

The information about the resource that will be evaluated.

Name Type Description
apiVersion

string

The api-version of the resource content.
resourceContent

object

The resource content. This should include whatever properties are already known and can be a partial set of all resource properties.
scope

string

The scope where the resource is being created. For example, if the resource is a child resource this would be the parent resource's resource ID.

CheckRestrictionsResult

The result of a check policy restrictions evaluation on a resource.

Name Type Description
contentEvaluationResult

ContentEvaluationResult

Evaluation results for the provided partial resource content.
fieldRestrictions

FieldRestrictions[]

The restrictions that will be placed on various fields in the resource by policy.

ContentEvaluationResult

Evaluation results for the provided partial resource content.

Name Type Description
policyEvaluations

PolicyEvaluationResult[]

Policy evaluation results against the given resource content. This will indicate if the partial content that was provided will be denied as-is.

ErrorDefinition

Error definition.

Name Type Description
additionalInfo

TypedErrorInfo[]

Additional scenario specific error details.
code

string

Service specific error code which serves as the substatus for the HTTP error code.
details

ErrorDefinition[]

Internal error details.
message

string

Description of the error.
target

string

The target of the error.

ErrorResponse

Error response.

Name Type Description
error

ErrorDefinition

The error details.

ExpressionEvaluationDetails

Evaluation details of policy language expressions.

Name Type Description
expression

string

Expression evaluated.
expressionKind

string

The kind of expression that was evaluated.
expressionValue

object

Value of the expression.
operator

string

Operator to compare the expression value and the target value.
path

string

Property path if the expression is a field or an alias.
result

string

Evaluation result.
targetValue

object

Target value to be compared with the expression value.

FieldRestriction

The restrictions on a field imposed by a specific policy.

Name Type Description
defaultValue

string

The value that policy will set for the field if the user does not provide a value.
policy

PolicyReference

The details of the policy that is causing the field restriction.
policyEffect

string

The effect of the policy that is causing the field restriction. http://aka.ms/policyeffects
reason

string

The reason for the restriction.
result

FieldRestrictionResult

The type of restriction that is imposed on the field.
values

string[]

The values that policy either requires or denies for the field.

FieldRestrictionResult

The type of restriction that is imposed on the field.

Name Type Description
Audit

string

The field and/or values will be audited by policy.
Deny

string

The field and/or values will be denied by policy.
Removed

string

The field will be removed by policy.
Required

string

The field and/or values are required by policy.

FieldRestrictions

The restrictions that will be placed on a field in the resource by policy.

Name Type Description
field

string

The name of the field. This can be a top-level property like 'name' or 'type' or an Azure Policy field alias.
restrictions

FieldRestriction[]

The restrictions placed on that field by policy.

IfNotExistsEvaluationDetails

Evaluation details of IfNotExists effect.

Name Type Description
resourceId

string

ID of the last evaluated resource for IfNotExists effect.
totalResources

integer

Total number of resources to which the existence condition is applicable.

PendingField

A field that should be evaluated against Azure Policy to determine restrictions.

Name Type Description
field

string

The name of the field. This can be a top-level property like 'name' or 'type' or an Azure Policy field alias.
values

string[]

The list of potential values for the field that should be evaluated against Azure Policy.

PolicyEffectDetails

The details of the effect that was applied to the resource.

Name Type Description
policyEffect

string

The effect that was applied to the resource. http://aka.ms/policyeffects

PolicyEvaluationResult

The result of a non-compliant policy evaluation against the given resource content.

Name Type Description
effectDetails

PolicyEffectDetails

The details of the effect that was applied to the resource.
evaluationDetails

CheckRestrictionEvaluationDetails

The detailed results of the policy expressions and values that were evaluated.
evaluationResult

string

The result of the policy evaluation against the resource. This will typically be 'NonCompliant' but may contain other values if errors were encountered.
policyInfo

PolicyReference

The details of the policy that was evaluated.

PolicyReference

Resource identifiers for a policy.

Name Type Description
policyAssignmentId

string

The resource identifier of the policy assignment.
policyDefinitionId

string

The resource identifier of the policy definition.
policyDefinitionReferenceId

string

The reference identifier of a specific policy definition within a policy set definition.
policySetDefinitionId

string

The resource identifier of the policy set definition.

TypedErrorInfo

Scenario specific error details.

Name Type Description
info

The scenario specific error details.
type

string

The type of included error details.