0
# Azure Policy Insights Client Library
1

2
## Overview
3

4
The Azure Policy Insights Client Library provides comprehensive programmatic access to Azure Policy services, enabling developers to query policy compliance states, policy events, policy metadata, remediations, tracked resources, and policy restrictions. This library supports both synchronous and asynchronous operations and integrates seamlessly with Azure authentication and management workflows.
5

6
## Package Information
7

8
- **Package Name**: azure-mgmt-policyinsights
9
- **Language**: Python  
10
- **Installation**: `pip install azure-mgmt-policyinsights`
11
- **Version**: 1.0.0
12
- **License**: MIT
13

14
## Core Imports
15

16
```python
17
# Main synchronous client
18
from azure.mgmt.policyinsights import PolicyInsightsClient
19

20
# Asynchronous client
21
from azure.mgmt.policyinsights.aio import PolicyInsightsClient as AsyncPolicyInsightsClient
22

23
# Models and data types
24
from azure.mgmt.policyinsights.models import (
25
    PolicyEvent,
26
    PolicyState,
27
    Remediation,
28
    PolicyMetadata,
29
    CheckRestrictionsRequest,
30
    FieldRestrictionResult,
31
    PolicyStatesResource,
32
    ResourceDiscoveryMode
33
)
34
```
35

36
## Basic Usage
37

38
### Client Authentication and Initialization
39

40
```python
41
from azure.identity import DefaultAzureCredential
42
from azure.mgmt.policyinsights import PolicyInsightsClient
43

44
# Initialize client with Azure credentials
45
credential = DefaultAzureCredential()
46
subscription_id = "your-subscription-id"
47
client = PolicyInsightsClient(credential, subscription_id)
48

49
# Context manager usage for automatic cleanup
50
with PolicyInsightsClient(credential, subscription_id) as client:
51
    # Use client operations
52
    pass
53
```
54

55
### Asynchronous Client Usage  
56

57
```python
58
from azure.identity.aio import DefaultAzureCredential
59
from azure.mgmt.policyinsights.aio import PolicyInsightsClient
60

61
async def async_example():
62
    credential = DefaultAzureCredential()
63
    async with PolicyInsightsClient(credential, subscription_id) as client:
64
        # Use async client operations
65
        pass
66
```
67

68
## Core Capabilities
69

70
### Policy States Management
71
Query and summarize policy compliance states across different Azure scopes (management groups, subscriptions, resource groups, and individual resources). Supports filtering, triggering evaluations, and comprehensive compliance reporting.
72

73
```python
74
# Query policy states for subscription  
75
policy_states = client.policy_states.list_query_results_for_subscription(
76
    subscription_id=subscription_id,
77
    policy_states_resource="latest"
78
)
79

80
# Summarize compliance for resource group
81
summary = client.policy_states.summarize_for_resource_group(
82
    resource_group_name="my-rg",
83
    subscription_id=subscription_id
84
)
85
```
86

87
**Details**: [Policy States Operations](./policy-states.md)
88

89
### Policy Events Monitoring
90
Query policy evaluation events to track when policies are evaluated and what results are produced. Essential for compliance monitoring and auditing workflows.
91

92
```python
93
# Query policy events for subscription
94
events = client.policy_events.list_query_results_for_subscription(
95
    subscription_id=subscription_id
96
)
97

98
# Query events for specific resource
99
resource_events = client.policy_events.list_query_results_for_resource(
100
    resource_id="/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/{provider}/{resource}"
101
)
102
```
103

104
**Details**: [Policy Events Operations](./policy-events.md)
105

106
### Remediation Management  
107
Create, manage, and monitor policy remediations to automatically fix non-compliant resources. Supports management group, subscription, resource group, and individual resource scopes.
108

109
```python
110
# Create remediation at subscription level
111
remediation = client.remediations.create_or_update_at_subscription(
112
    subscription_id=subscription_id,
113
    remediation_name="fix-non-compliant-resources",
114
    parameters={
115
        "properties": {
116
            "policyAssignmentId": "/subscriptions/{sub}/providers/Microsoft.Authorization/policyAssignments/{assignment}",
117
            "resourceDiscoveryMode": "ExistingNonCompliant"
118
        }
119
    }
120
)
121

122
# List remediation deployments
123
deployments = client.remediations.list_deployments_at_subscription(
124
    subscription_id=subscription_id,
125
    remediation_name="fix-non-compliant-resources"
126
)
127
```
128

129
**Details**: [Remediations Operations](./remediations.md)
130

131
### Policy Metadata Discovery
132
Access policy metadata including built-in policy definitions, categories, and detailed policy information for governance and compliance workflows.
133

134
```python
135
# List all policy metadata
136
metadata_list = client.policy_metadata.list()
137

138
# Get specific policy metadata
139
metadata = client.policy_metadata.get_resource(
140
    resource_name="policy-metadata-name"
141
)
142
```
143

144
**Details**: [Policy Metadata Operations](./policy-metadata.md)
145

146
### Policy Tracked Resources
147
Query resources that are tracked by Azure Policy to understand which resources are being monitored for compliance.
148

149
```python
150
# Query tracked resources for subscription
151
tracked_resources = client.policy_tracked_resources.list_query_results_for_subscription(
152
    subscription_id=subscription_id
153
)
154
```
155

156
**Details**: [Policy Tracked Resources Operations](./policy-tracked-resources.md)
157

158
### Policy Restrictions Validation
159
Check what policy restrictions would apply to resource operations before attempting to perform them, enabling proactive compliance validation.
160

161
```python
162
from azure.mgmt.policyinsights.models import CheckRestrictionsRequest
163

164
# Check restrictions for subscription scope
165
request = CheckRestrictionsRequest(
166
    resource_details={
167
        "resource_content": {"location": "eastus", "kind": "web"},
168
        "api_version": "2021-01-01"
169
    }
170
)
171

172
restrictions = client.policy_restrictions.check_at_subscription_scope(
173
    subscription_id=subscription_id,
174
    parameters=request
175
)
176
```
177

178
**Details**: [Policy Restrictions Operations](./policy-restrictions.md)
179

180
### Operations Discovery
181
Query available operations and capabilities provided by the Policy Insights service for programmatic discovery of supported API functionality.
182

183
```python { .api }
184
# List all available operations
185
operations = client.operations.list()
186
```
187

188
Usage example:
189

190
```python
191
# Discover available operations
192
operations_list = client.operations.list()
193
for operation in operations_list:
194
    print(f"Operation: {operation.name}")
195
    print(f"Display Name: {operation.display.operation}")
196
    print(f"Description: {operation.display.description}")
197
```
198

199
## Architecture
200

201
The Azure Policy Insights Client Library follows the Azure SDK design patterns:
202

203
- **Client Class**: `PolicyInsightsClient` serves as the main entry point with operation groups as properties
204
- **Operation Groups**: Seven specialized operation classes handle different policy aspects:
205
  - `policy_states`: Policy compliance state queries and summaries
206
  - `policy_events`: Policy evaluation event queries
207
  - `remediations`: Policy remediation management
208
  - `policy_metadata`: Policy metadata and definition discovery
209
  - `policy_tracked_resources`: Tracked resource queries
210
  - `policy_restrictions`: Policy restriction validation
211
  - `operations`: API operation discovery
212
- **Models**: Comprehensive data models for all API interactions
213
- **Authentication**: Integrates with Azure Identity for credential management
214
- **Async Support**: Full async/await support through the `aio` module
215
- **Error Handling**: Consistent error handling with Azure-specific exception types
216

217
## Error Handling
218

219
The library uses standard Azure SDK exceptions:
220

221
```python
222
from azure.core.exceptions import HttpResponseError, ClientAuthenticationError
223

224
try:
225
    policy_states = client.policy_states.list_query_results_for_subscription(
226
        subscription_id=subscription_id,
227
        policy_states_resource="latest"
228
    )
229
except ClientAuthenticationError:
230
    # Handle authentication issues
231
    pass
232
except HttpResponseError as e:
233
    # Handle HTTP errors (4xx, 5xx)
234
    print(f"HTTP error: {e.status_code} - {e.message}")
235
```