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

HTTP

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

HTTP

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.

Share via

Policy Restrictions - Check At Resource Group Scope

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Check policy restrictions at resource group scope

Sample request

Sample response

Check policy restrictions at resource group scope including audit effect

Sample request

Sample response

Definitions

CheckRestrictionEvaluationDetails

CheckRestrictionsRequest

CheckRestrictionsResourceDetails

CheckRestrictionsResult

ContentEvaluationResult

ErrorDefinition

ErrorResponse

ExpressionEvaluationDetails

FieldRestriction

FieldRestrictionResult

FieldRestrictions

IfNotExistsEvaluationDetails

PendingField

PolicyEffectDetails

PolicyEvaluationResult

PolicyReference

TypedErrorInfo

Additional resources