[FEATURE REQ] Insufficient documentation or examples for resource type policy_assignments

[ChenxiJiang333]

API Spec link

https://github.com/Azure/azure-rest-api-specs/blob/main/specification/resources/resource-manager/Microsoft.Authorization/stable/2025-01-01/policyAssignments.json#L1029

API Spec version

2025-01-01

Please describe the feature.

According to customer report, documentation for resource type policy_assignments could be improved:

1. Operation policy_assignment.update_by_id made the most sense from its name to update policy assignment, but it does not support update policy assignment parameters. It could only be done by using policy_assignment.create_by_id.
2. It seems it's lack of support to simply append or reduce policy assignment parameters values. For now, it only supports totally replacing them.
3. By using policy_assignment.create_by_id, you need to specify policyDefinitionId, which is not documented required.

[microsoft-github-policy-service]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @darshanhs90, @AshishGargMicrosoft.