你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure PIM 通过 REST API 管理符合条件的访问权限

使用 Azure Privileged Identity Management (PIM) ，可以限制对特权角色的常备管理员访问权限、发现谁具有访问权限并查看特权访问权限。 本文介绍使用 REST API 管理访问权限的常见方法。

列出符合条件的分配

若要列出合格角色分配 (列出访问) ，可以使用 角色资格计划实例之一 - 范围列表 或 角色资格计划 - 范围 REST API 列表。 若要优化结果，请指定一个范围和可选的筛选器。 若要调用 API，必须具有对指定范围的 Microsoft.Authorization/roleAssignments/read 操作的访问权限。 所有 内置角色 都被授予对此操作的访问权限。

重要

计划和计划实例之间的区别在于，虽然计划实例仅包括当前处于活动状态的分配，但计划还包括将来将处于活动状态的分配。

1. 从下面的请求开始：

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleInstances?api-version=2020-10-01&$filter={filter}
   

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilitySchedules?api-version=2020-10-01&$filter={filter}
   

2. 在 URI 中，将“{scope}”替换为要列出角色分配的范围。

   作用域	类型
   providers/Microsoft.Management/managementGroups/{mg-name}	管理组
   subscriptions/{subscriptionId}	订阅
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	资源组
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1	资源

3. 将“{filter}”替换为筛选角色分配列表时要应用的条件。

   筛选器	说明
   $filter=atScope()	只列出指定范围内的角色分配，而不包括子范围内的角色分配。
   $filter=principalId%20eq%20'{objectId}'	列出特定用户、组或服务主体的角色分配。
   $filter=roleDefinitionId%20eq%20'{roleDefinitionId}'	列出指定角色定义的角色分配。
   $filter=assignedTo('{objectId}')	列出特定用户（包括继承自组的用户）的角色分配。
   $filter=asTarget()	列出当前用户或服务主体的角色分配，包括从组继承的角色分配。
   $filter=assignedTo('{objectId}')+and+atScope()	列出指定用户的角色分配，包括仅针对指定范围（不包括子作用域中的角色分配）从组继承的角色分配。

授予符合条件的分配

若要创建合格角色分配 (授予访问权限) ，请使用 角色资格计划请求 - 创建 REST API 并指定安全主体、角色定义、计划、requestType = AdminAssign 和范围。 若要调用此 API，必须有权访问 Microsoft.Authorization/roleAssignments/write 操作。 在内置角色中，只有所有者和用户访问管理员具有对此操作的访问权限。

1. 使用角色定义 - List REST API 或参阅内置角色，获取你想要分配的角色定义的标识符。

2. 使用 GUID 工具生成将用于角色分配标识符的唯一标识符。 标识符的格式为：00000000-0000-0000-0000-000000000000

3. 从以下请求和正文开始：

   PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/{roleEligibilityScheduleRequestName}?api-version=2020-10-01
   

   {
     "Properties": {
       "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
       "PrincipalId": "{principalId}",
       "RequestType": "AdminAssign",
       "ScheduleInfo": {
         "StartDateTime": "2020-09-09T21:31:27.91Z",
         "Expiration": {
           "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
           "EndDateTime": null,
           "Duration": "P365D" // Use ISO 8601 format
         }
       }
     }
   }
   

4. 在 URI 内，将“{scope}”替换为角色分配的范围。

   作用域	类型
   providers/Microsoft.Management/managementGroups/{mg-name}	管理组
   subscriptions/{subscriptionId}	订阅
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	资源组
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1	资源

5. 将 {roleEligibilityScheduleRequestName} 替换为角色分配的 GUID 标识符。

6. 在请求正文中，将“{subscriptionId}”替换为你的订阅标识符。

7. 将“{roleDefinitionId}”替换为角色定义标识符。

8. 将“{principalId}”替换为将分配有角色的用户、组或服务主体的对象标识符。

删除符合条件的分配

若要删除符合条件的角色分配 (删除访问权限) ，请使用 角色资格计划请求 - 创建 REST API 创建撤销分配的新请求，并指定安全主体、角色定义、requestType = AdminRemove 和范围。 若要调用此 API，必须具有对 Microsoft.Authorization/roleAssignments/write 操作的访问权限。 在内置角色中，只有所有者和用户访问管理员具有对此操作的访问权限。

1. 使用 GUID 工具生成将用于角色分配标识符的唯一标识符。 标识符的格式为：00000000-0000-0000-0000-000000000000

2. 从下面的请求开始：

   PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/{roleEligibilityScheduleRequestName}?api-version=2020-10-01
   

   {
     "Properties": {
       "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
       "PrincipalId": "{principalId}",
       "RequestType": "AdminRemove"
       }
   }
   

3. 在 URI 内，将“{scope}”替换为删除角色分配的范围。

   作用域	类型
   providers/Microsoft.Management/managementGroups/{mg-name}	管理组
   subscriptions/{subscriptionId}	订阅
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	资源组
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1	资源

4. 将 {roleEligibilityScheduleRequestName} 替换为角色分配的 GUID 标识符。

新请求返回的常见错误

下面是创建新请求时可能会遇到的常见错误及其缓解方式的列表。

错误消息	Explanantion	缓解措施
code：RoleAssignmentExists message：角色分配已存在。	已存在类似的角色分配	可以 GET 分配此角色并验证其计划。
code：RoleAssignmentRequestPolicyValidationFailed message：以下策略规则失败：[“ExpirationRule”]	ScheduleInfo请求中指定的 超过允许的最长持续时间	可以GET为此RoleDefinitionId使用 RoleManagementPolicy，检查RoleManagementPolicyExpirationRule
code：RoleAssignmentRequestPolicyValidationFailed message：以下策略规则失败：[“JustificationRule”]	需要在请求正文中指定Justification	可以GET为此RoleDefinitionId使用 RoleManagementPolicy，检查RoleManagementPolicyEnablementRule
code：RoleAssignmentRequestPolicyValidationFailed message：以下策略规则失败：[“EligibilityRule”]	不存在用于激活此角色的有效 RoleEligibilityScheduleInstance 值	资源管理员需要为此主体创建RoleEligibilityScheduleRequest
code：RoleAssignmentRequestPolicyValidationFailed message：以下策略规则失败：[“TicketingRule”]	需要在请求正文中指定TicketInfo	可以GET为此RoleDefinitionId使用 RoleManagementPolicy，检查RoleManagementPolicyEnablementRule
code：RoleAssignmentRequestPolicyValidationFailed message：以下策略规则失败：[“MfaRule”]	需要完成 Azure 多重身份验证才能提交此请求	可以GET为此RoleDefinitionId使用 RoleManagementPolicy，检查RoleManagementPolicyEnablementRule