你当前正在访问 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 标识符。

为新请求返回的常见错误

下面是创建新请求时可能会遇到的常见错误列表，以及如何缓解这些错误。

错误消息	外部计划	缓解措施
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