Policy States - Summarize For Management Group

Service:

Policy

API Version:

2019-10-01

Summarizes policy states for the resources under the management group.

POST https://management.azure.com/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/Microsoft.PolicyInsights/policyStates/latest/summarize?api-version=2019-10-01

With optional parameters:

POST https://management.azure.com/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/Microsoft.PolicyInsights/policyStates/latest/summarize?api-version=2019-10-01&$top={$top}&$from={$from}&$to={$to}&$filter={$filter}

URI Parameters

Name	In	Required	Type	Description
managementGroupName	path	True	string	Management group name.
managementGroupsNamespace	path	True	ManagementGroupsNamespaceType	The namespace for Microsoft Management RP; only "Microsoft.Management" is allowed.
policyStatesSummaryResource	path	True	PolicyStatesSummaryResourceType	The virtual resource under PolicyStates resource type for summarize action. In a given time range, 'latest' represents the latest policy state(s) and is the only allowed value.
api-version	query	True	string	Client Api Version.
$filter	query		string	OData filter expression.
$from	query		string date-time	ISO 8601 formatted timestamp specifying the start time of the interval to query. When not specified, the service uses ($to - 1-day).
$to	query		string date-time	ISO 8601 formatted timestamp specifying the end time of the interval to query. When not specified, the service uses request time.
$top	query		integer int32	Maximum number of records to return.

Responses

Name	Type	Description
200 OK	SummarizeResults	Summarize results.
Other Status Codes	QueryFailure	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

Summarize at management group scope

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/latest/summarize?api-version=2019-10-01&$top=0&$from=2019-10-05T18:00:00Z&$to=2019-10-06T18:00:00Z&$filter=PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit'

Java

import com.azure.resourcemanager.policyinsights.models.PolicyStatesSummaryResourceType;
import java.time.OffsetDateTime;

/**
 * Samples for PolicyStates SummarizeForManagementGroup.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/policyinsights/resource-manager/Microsoft.PolicyInsights/stable/2019-10-01/examples/
     * PolicyStates_SummarizeManagementGroupScope.json
     */
    /**
     * Sample code: Summarize at management group scope.
     * 
     * @param manager Entry point to PolicyInsightsManager.
     */
    public static void
        summarizeAtManagementGroupScope(com.azure.resourcemanager.policyinsights.PolicyInsightsManager manager) {
        manager.policyStates().summarizeForManagementGroupWithResponse(PolicyStatesSummaryResourceType.LATEST,
            "myManagementGroup", 0, OffsetDateTime.parse("2019-10-05T18:00:00Z"),
            OffsetDateTime.parse("2019-10-06T18:00:00Z"),
            "PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit'", com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Python

from azure.identity import DefaultAzureCredential
from azure.mgmt.policyinsights import PolicyInsightsClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-policyinsights
# USAGE
    python policy_states_summarize_management_group_scope.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = PolicyInsightsClient(
        credential=DefaultAzureCredential(),
        subscription_id="SUBSCRIPTION_ID",
    )

    response = client.policy_states.summarize_for_management_group(
        policy_states_summary_resource="latest",
        management_group_name="myManagementGroup",
    )
    print(response)


# x-ms-original-file: specification/policyinsights/resource-manager/Microsoft.PolicyInsights/stable/2019-10-01/examples/PolicyStates_SummarizeManagementGroupScope.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Go

package armpolicyinsights_test

import (
	"context"
	"log"

	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/policyinsights/armpolicyinsights"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/05a9cdab363b8ec824094ee73950c04594325172/specification/policyinsights/resource-manager/Microsoft.PolicyInsights/stable/2019-10-01/examples/PolicyStates_SummarizeManagementGroupScope.json
func ExamplePolicyStatesClient_SummarizeForManagementGroup() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armpolicyinsights.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	res, err := clientFactory.NewPolicyStatesClient().SummarizeForManagementGroup(ctx, armpolicyinsights.PolicyStatesSummaryResourceTypeLatest, "myManagementGroup", &armpolicyinsights.QueryOptions{Top: to.Ptr[int32](0),
		Filter:    to.Ptr("PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit'"),
		OrderBy:   nil,
		Select:    nil,
		From:      to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2019-10-05T18:00:00.000Z"); return t }()),
		To:        to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2019-10-06T18:00:00.000Z"); return t }()),
		Apply:     nil,
		SkipToken: nil,
		Expand:    nil,
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.SummarizeResults = armpolicyinsights.SummarizeResults{
	// 	ODataContext: to.Ptr("https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/$metadata#summary"),
	// 	ODataCount: to.Ptr[int32](1),
	// 	Value: []*armpolicyinsights.Summary{
	// 		{
	// 			ODataContext: to.Ptr("https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/$metadata#summary/$entity"),
	// 			PolicyAssignments: []*armpolicyinsights.PolicyAssignmentSummary{
	// 			},
	// 			Results: &armpolicyinsights.SummaryResults{
	// 				NonCompliantPolicies: to.Ptr[int32](68),
	// 				NonCompliantResources: to.Ptr[int32](15410),
	// 				PolicyDetails: []*armpolicyinsights.ComplianceDetail{
	// 					{
	// 						ComplianceState: to.Ptr("noncompliant"),
	// 						Count: to.Ptr[int32](68),
	// 				}},
	// 				PolicyGroupDetails: []*armpolicyinsights.ComplianceDetail{
	// 					{
	// 						ComplianceState: to.Ptr("noncompliant"),
	// 						Count: to.Ptr[int32](14),
	// 				}},
	// 				QueryResultsURI: to.Ptr("https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2019-10-01&$from=2019-10-05 18:00:00Z&$to=2019-10-06 18:00:00Z&$filter=(PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit') and IsCompliant eq false"),
	// 				ResourceDetails: []*armpolicyinsights.ComplianceDetail{
	// 					{
	// 						ComplianceState: to.Ptr("compliant"),
	// 						Count: to.Ptr[int32](1400),
	// 					},
	// 					{
	// 						ComplianceState: to.Ptr("noncompliant"),
	// 						Count: to.Ptr[int32](15410),
	// 				}},
	// 			},
	// 	}},
	// }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { PolicyInsightsClient } = require("@azure/arm-policyinsights");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to Summarizes policy states for the resources under the management group.
 *
 * @summary Summarizes policy states for the resources under the management group.
 * x-ms-original-file: specification/policyinsights/resource-manager/Microsoft.PolicyInsights/stable/2019-10-01/examples/PolicyStates_SummarizeManagementGroupScope.json
 */
async function summarizeAtManagementGroupScope() {
  const subscriptionId =
    process.env["POLICYINSIGHTS_SUBSCRIPTION_ID"] || "00000000-0000-0000-0000-000000000000";
  const policyStatesSummaryResource = "latest";
  const managementGroupName = "myManagementGroup";
  const top = 0;
  const fromParam = new Date("2019-10-05T18:00:00Z");
  const to = new Date("2019-10-06T18:00:00Z");
  const filter = "PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit'";
  const options = {
    queryOptions: { top: top, from: fromParam, to: to, filter: filter },
  };
  const credential = new DefaultAzureCredential();
  const client = new PolicyInsightsClient(credential, subscriptionId);
  const result = await client.policyStates.summarizeForManagementGroup(
    policyStatesSummaryResource,
    managementGroupName,
    options
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

dotnet

using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ManagementGroups;
using Azure.ResourceManager.PolicyInsights;
using Azure.ResourceManager.PolicyInsights.Models;

// Generated from example definition: specification/policyinsights/resource-manager/Microsoft.PolicyInsights/stable/2019-10-01/examples/PolicyStates_SummarizeManagementGroupScope.json
// this example is just showing the usage of "PolicyStates_SummarizeForManagementGroup" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this ManagementGroupResource created on azure
// for more information of creating ManagementGroupResource, please refer to the document of ManagementGroupResource
string managementGroupName = "myManagementGroup";
ResourceIdentifier managementGroupResourceId = ManagementGroupResource.CreateResourceIdentifier(managementGroupName);
ManagementGroupResource managementGroupResource = client.GetManagementGroupResource(managementGroupResourceId);

// invoke the operation and iterate over the result
PolicyStateSummaryType policyStateSummaryType = PolicyStateSummaryType.Latest;
await foreach (PolicySummary item in managementGroupResource.SummarizePolicyStatesAsync(policyStateSummaryType))
{
    Console.WriteLine($"Succeeded: {item}");
}

Console.WriteLine($"Succeeded");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample response

Status code:

200

{
  "@odata.context": "https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/$metadata#summary",
  "@odata.count": 1,
  "value": [
    {
      "@odata.id": null,
      "@odata.context": "https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/$metadata#summary/$entity",
      "results": {
        "queryResultsUri": "https://management.azure.com/providers/Microsoft.Management/managementGroups/myManagementGroup/providers/Microsoft.PolicyInsights/policyStates/latest/queryResults?api-version=2019-10-01&$from=2019-10-05 18:00:00Z&$to=2019-10-06 18:00:00Z&$filter=(PolicyDefinitionAction eq 'deny' or PolicyDefinitionAction eq 'audit') and IsCompliant eq false",
        "nonCompliantResources": 15410,
        "nonCompliantPolicies": 68,
        "resourceDetails": [
          {
            "complianceState": "compliant",
            "count": 1400
          },
          {
            "complianceState": "noncompliant",
            "count": 15410
          }
        ],
        "policyDetails": [
          {
            "complianceState": "noncompliant",
            "count": 68
          }
        ],
        "policyGroupDetails": [
          {
            "complianceState": "noncompliant",
            "count": 14
          }
        ]
      },
      "policyAssignments": []
    }
  ]
}

Definitions

Name	Description
ComplianceDetail	The compliance state rollup.
Error	Error definition.
ManagementGroupsNamespaceType	The namespace for Microsoft Management RP; only "Microsoft.Management" is allowed.
PolicyAssignmentSummary	Policy assignment summary.
PolicyDefinitionSummary	Policy definition summary.
PolicyGroupSummary	Policy definition group summary.
PolicyStatesSummaryResourceType	The virtual resource under PolicyStates resource type for summarize action. In a given time range, 'latest' represents the latest policy state(s) and is the only allowed value.
QueryFailure	Error response.
SummarizeResults	Summarize action results.
Summary	Summary results.
SummaryResults	Compliance summary on a particular summary level.

ComplianceDetail

The compliance state rollup.

Name	Type	Description
complianceState	string	The compliance state.
count	integer	Summarized count value for this compliance state.

Error

Error definition.

Name	Type	Description
code	string	Service specific error code which serves as the substatus for the HTTP error code.
message	string	Description of the error.

ManagementGroupsNamespaceType

The namespace for Microsoft Management RP; only "Microsoft.Management" is allowed.

Name	Type	Description
Microsoft.Management	string

PolicyAssignmentSummary

Policy assignment summary.

Name	Type	Description
policyAssignmentId	string	Policy assignment ID.
policyDefinitions	PolicyDefinitionSummary[]	Policy definitions summary.
policyGroups	PolicyGroupSummary[]	Policy definition group summary.
policySetDefinitionId	string	Policy set definition ID, if the policy assignment is for a policy set.
results	SummaryResults	Compliance summary for the policy assignment.

PolicyDefinitionSummary

Policy definition summary.

Name	Type	Description
effect	string	Policy effect, i.e. policy definition action.
policyDefinitionGroupNames	string[]	Policy definition group names.
policyDefinitionId	string	Policy definition ID.
policyDefinitionReferenceId	string	Policy definition reference ID.
results	SummaryResults	Compliance summary for the policy definition.

PolicyGroupSummary

Policy definition group summary.

Name	Type	Description
policyGroupName	string	Policy group name.
results	SummaryResults	Compliance summary for the policy definition group.

PolicyStatesSummaryResourceType

The virtual resource under PolicyStates resource type for summarize action. In a given time range, 'latest' represents the latest policy state(s) and is the only allowed value.

Name	Type	Description
latest	string

QueryFailure

Error response.

Name	Type	Description
error	Error	Error definition.

SummarizeResults

Summarize action results.

Name	Type	Description
@odata.context	string	OData context string; used by OData clients to resolve type information based on metadata.
@odata.count	integer	OData entity count; represents the number of summaries returned; always set to 1.
value	Summary[]	Summarize action results.

Summary

Summary results.

Name	Type	Description
@odata.context	string	OData context string; used by OData clients to resolve type information based on metadata.
@odata.id	string	OData entity ID; always set to null since summaries do not have an entity ID.
policyAssignments	PolicyAssignmentSummary[]	Policy assignments summary.
results	SummaryResults	Compliance summary for all policy assignments.

SummaryResults

Compliance summary on a particular summary level.

Name	Type	Description
nonCompliantPolicies	integer	Number of non-compliant policies.
nonCompliantResources	integer	Number of non-compliant resources.
policyDetails	ComplianceDetail[]	The policy artifact summary at this level. For query scope level, it represents policy assignment summary. For policy assignment level, it represents policy definitions summary.
policyGroupDetails	ComplianceDetail[]	The policy definition group summary at this level.
queryResultsUri	string	HTTP POST URI for queryResults action on Microsoft.PolicyInsights to retrieve raw results for the compliance summary. This property will not be available by default in future API versions, but could be queried explicitly.
resourceDetails	ComplianceDetail[]	The resources summary at this level.