Get-AzPolicyState

Gets policy compliance states for resources.

Syntax

Get-AzPolicyState
   [-All]
   [-SubscriptionId <String>]
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   -ManagementGroupName <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   [-SubscriptionId <String>]
   -ResourceGroupName <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   -ResourceId <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-Expand <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   [-SubscriptionId <String>]
   -PolicySetDefinitionName <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   [-SubscriptionId <String>]
   -PolicyDefinitionName <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   [-SubscriptionId <String>]
   -PolicyAssignmentName <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
Get-AzPolicyState
   [-All]
   [-SubscriptionId <String>]
   -ResourceGroupName <String>
   -PolicyAssignmentName <String>
   [-Top <Int32>]
   [-OrderBy <String>]
   [-Select <String>]
   [-From <DateTime>]
   [-To <DateTime>]
   [-Filter <String>]
   [-Apply <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]

Description

Gets policy compliance states for resources. Policy state records can be queried at various scopes. Based on the time interval specified (defaults to last day), either latest policy states or all policy state transitions can be queried. Results can be filtered, grouped, and group aggregations can be computed.

Examples

Example 1: Get latest policy states in current subscription scope

PS C:\> Get-AzPolicyState

Gets latest policy state records generated in the last day for all resources within the subscription in current session context.

Example 2: Get latest policy states in the specified subscription scope

PS C:\> Get-AzPolicyState -SubscriptionId "fff10b27-fff3-fff5-fff8-fffbe01e86a5"

Gets latest policy state records generated in the last day for all resources within the specified subscription.

Example 3: Get all policy states in current subscription scope

PS C:\> Get-AzPolicyState -All

Gets all historical policy state records (including latest) generated in the last day for all resources within the subscription in current session context.

Example 4: Get latest policy states in management group scope

PS C:\> Get-AzPolicyState -ManagementGroupName "myManagementGroup"

Gets latest policy state records generated in the last day for all resources within the specified management group.

Example 5: Get latest policy states in resource group scope in current subscription

PS C:\> Get-AzPolicyState -ResourceGroupName "myResourceGroup"

Gets latest policy state records generated in the last day for all resources within the specified resource group (in the subscription in current session context).

Example 6: Get latest policy states in resource group scope in the specified subscription

PS C:\> Get-AzPolicyState -SubscriptionId "fff10b27-fff3-fff5-fff8-fffbe01e86a5" -ResourceGroupName "myResourceGroup"

Gets latest policy state records generated in the last day for all resources within the specified resource group (in the specified subscription).

Example 7: Get latest policy states for a resource

PS C:\> Get-AzPolicyState -ResourceId "/subscriptions/fff10b27-fff3-fff5-fff8-fffbe01e86a5/resourceGroups/myResourceGroup/providers/Microsoft.EventHub/namespaces/myns1/eventhubs/eh1/consumergroups/cg1"

Gets latest policy state records generated in the last day for the specified resource.

Example 8: Get latest policy states for a policy set definition in current subscription

PS C:\> Get-AzPolicyState -PolicySetDefinitionName "fff58873-fff8-fff5-fffc-fffbe7c9d697"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy set definition (that exists in the subscription in current session context).

Example 9: Get latest policy states for a policy set definition in the specified subscription

PS C:\> Get-AzPolicyState -SubscriptionId "fff10b27-fff3-fff5-fff8-fffbe01e86a5" -PolicySetDefinitionName "fff58873-fff8-fff5-fffc-fffbe7c9d697"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy set definition (that exists in the specified subscription).

Example 10: Get latest policy states for a policy definition in current subscription

PS C:\> Get-AzPolicyState -PolicyDefinitionName "fff58873-fff8-fff5-fffc-fffbe7c9d697"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy definition (that exists in the subscription in current session context).

Example 11: Get latest policy states for a policy definition in the specified subscription

PS C:\> Get-AzPolicyState -SubscriptionId "fff10b27-fff3-fff5-fff8-fffbe01e86a5" -PolicyDefinitionName "fff58873-fff8-fff5-fffc-fffbe7c9d697"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy definition (that exists in the specified subscription).

Example 12: Get latest policy states for a policy assignment in current subscription

PS C:\> Get-AzPolicyState -PolicyAssignmentName "ddd8ef92e3714a5ea3d208c1"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy assignment (that exists in the subscription in current session context).

Example 13: Get latest policy states for a policy assignment in the specified subscription

PS C:\> Get-AzPolicyState -SubscriptionId "fff10b27-fff3-fff5-fff8-fffbe01e86a5" -PolicyAssignmentName "ddd8ef92e3714a5ea3d208c1"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy assignment (that exists in the specified subscription).

Example 14: Get latest policy states for a policy assignment in the specified resource group in the current subscription

PS C:\> Get-AzPolicyState -ResourceGroupName "myResourceGroup" -PolicyAssignmentName "ddd8ef92e3714a5ea3d208c1"

Gets latest policy state records generated in the last day for all resources (within the tenant in current session context) effected by the specified policy assignment (that exists in the resource group in the subscription in current session context).

Example 15: Get latest policy states in current subscription scope, with OrderBy, Top and Select query options

PS C:\> Get-AzPolicyState -OrderBy "Timestamp desc, PolicyAssignmentName asc" -Top 5 -Select "Timestamp, ResourceId, PolicyAssignmentId, PolicySetDefinitionId, PolicyDefinitionId, IsCompliant"

Gets latest policy state records generated in the last day for all resources within the subscription in current session context. The command orders the results by timestamp and policy assignment name properties, and takes only top 5 of those listed in that order. It also selects to list only a subset of the columns for each record.

Example 16: Get latest policy states in current subscription scope, with From and To query options

PS C:\> Get-AzPolicyState -From "2018-03-08 00:00:00Z" -To "2018-03-15 00:00:00Z"

Gets latest policy state records generated within the date range specified for all resources within the subscription in current session context.

Example 17: Get latest policy states in current subscription scope, with Filter query option

PS C:\> Get-AzPolicyState -Filter "(PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit') and IsCompliant eq false and ResourceLocation ne 'eastus'"

Gets latest policy state records generated in the last day for all resources within the subscription in current session context. The command limits the results returned by filtering based on policy definition action (includes deny or audit actions), compliance status (includes only non-compliant status) and resource location (excludes eastus location).

Example 18: Get latest policy states in current subscription scope, with Apply specifying row count aggregation

PS C:\> Get-AzPolicyState -Apply "aggregate(`$count as NumberOfRecords)"

Gets the number of latest policy state records generated in the last day for all resources within the subscription in current session context. The command returns the count of the policy state records only, which is returned inside AdditionalProperties property.

Example 19: Get latest policy states in current subscription scope, with Apply specifying grouping with aggregation

PS C:\> Get-AzPolicyState -Filter "IsCompliant eq false" -Apply "groupby((PolicyAssignmentId, PolicySetDefinitionId, PolicyDefinitionReferenceId, PolicyDefinitionId), aggregate(`$count as NumStates))" -OrderBy "NumStates desc" -Top 5

Gets latest policy state records generated in the last day for all resources within the subscription in current session context. The command limits the results returned by filtering based on compliance status (includes only non-compliant status). It groups the results based on policy assignment, policy set definition, and policy definition, and computes the number of records in each group, which is returned inside AdditionalProperties property. It orders the results by the count aggregation in descending order, and takes only top 5 of those listed in that order.

Example 20: Get latest policy states in current subscription scope, with Apply specifying grouping without aggregation

PS C:\> Get-AzPolicyState -Filter "IsCompliant eq false" -Apply "groupby((ResourceId))"

Gets latest policy state records generated in the last day for all resources within the subscription in current session context. The command limits the results returned by filtering based on compliance status (includes only non-compliant status). It groups the results based on resource id. This generates the list of all resources within the subscription that are non-compliant for at least one policy.

Example 21: Get latest policy states in current subscription scope, with Apply specifying multiple groupings

PS C:\> Get-AzPolicyState -Filter "IsCompliant eq false" -Apply "groupby((PolicyAssignmentId, PolicySetDefinitionId, PolicyDefinitionReferenceId, PolicyDefinitionId, ResourceId))/groupby((PolicyAssignmentId, PolicySetDefinitionId, PolicyDefinitionReferenceId, PolicyDefinitionId), aggregate(`$count as NumNonCompliantResources))" -OrderBy "NumNonCompliantResources desc" -Top 5

Example 22: Get latest policy states including policy evaluation details for a resource

PS C:\> Get-AzPolicyState -ResourceId "/subscriptions/fff10b27-fff3-fff5-fff8-fffbe01e86a5/resourceGroups/myResourceGroup/providers/Microsoft.EventHub/namespaces/myns1/eventhubs/eh1/consumergroups/cg1" -Expand "PolicyEvaluationDetails"

Gets latest policy state records generated in the last day for all resources within the subscription in current session context. The command limits the results returned by filtering based on compliance status (includes only non-compliant status). It groups the results first based on policy assignment, policy set definition, policy definition, and resource id. Then, it further groups the results of this grouping with the same properties except for resource id, and computes the number of records in each of these groups, which is returned inside AdditionalProperties property. It orders the results by the count aggregation in descending order, and takes only top 5 of those listed in that order. This generates the top 5 policies with the most number of non-compliant resources.

Parameters

-All

Within the specified time interval, get all policy states instead of the latest only.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Apply

Apply expression for aggregations using OData notation.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-DefaultProfile

The credentials, account, tenant, and subscription used for communication with Azure.

Type:Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer
Aliases:AzContext, AzureRmContext, AzureCredential
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Expand

Expand expression using OData notation.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Filter

Filter expression using OData notation.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-From

ISO 8601 formatted timestamp specifying the start time of the interval to query. When not specified, defaults to 'To' parameter value minus 1 day.

Type:DateTime
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ManagementGroupName

Management group name.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-OrderBy

Ordering expression using OData notation. One or more comma-separated column names with an optional 'desc' (the default) or 'asc'.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-PolicyAssignmentName

Policy assignment name.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-PolicyDefinitionName

Policy definition name.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-PolicySetDefinitionName

Policy set definition name.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-ResourceGroupName

Resource group name.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-ResourceId

Resource ID.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-Select

Select expression using OData notation. One or more comma-separated column names. Limits the columns on each record to just those requested.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-SubscriptionId

Subscription ID.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-To

ISO 8601 formatted timestamp specifying the end time of the interval to query. When not specified, defaults to time of request.

Type:DateTime
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Top

Maximum number of records to return.

Type:Int32
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Inputs

String

Outputs

Microsoft.Azure.Commands.PolicyInsights.Models.PolicyState