Privileged Identity Management API
Privileged Identity Management (PIM) 是 Microsoft Entra 的一部分，包括三个提供程序：
- 适用于 Microsoft Entra 角色的 PIM
- 适用于 Azure 资源的 PIM
- 适用于组的 PIM
可以使用 Microsoft Graph API 在适用于 Microsoft Entra 角色的 PIM 和适用于组的 PIM 中管理分配。 可以使用 Azure 资源管理器 (ARM) API 在 PIM 中管理 Azure 资源的分配。 本文介绍使用适用于 Privileged Identity Management 的 API 的重要概念。
在文档中查找有关允许管理分配的 API 的更多详细信息：
- 适用于 Microsoft Entra 角色的 PIM API 参考
- 适用于 Azure 资源角色的 PIM API 参考
- 适用于组的 PIM for API 参考
- 适用于 Microsoft Entra 角色的 PIM 警报 API 参考
- 适用于 Azure 资源的 PIM 警报 API 参考
PIM API 历史记录
在过去几年中，PIM API 已有几次迭代。 用户会发现一些功能重叠，但它们并不代表版本的线性进度。
迭代 1 - 已弃用
在 /beta/privilegedRoles 终结点下，Microsoft 有一个只支持 Microsoft Entra 角色的 PIM API 经典版本，现在已不再受支持。 在 2021 年 6 月已弃用对此 API 的访问。
迭代 2 – 支持 Microsoft Entra 角色和 Azure 资源角色
在 /beta/privilegedAccess 终结点下，Microsoft 支持 /aadRoles 和 /azureResources。 此终结点在租户中仍可用，但 Microsoft 建议不要使用此 API 开始任何新的开发工作。 此 beta 版 API 永远不会正式发布，且最终会被弃用。
迭代 3（当前）– Microsoft Graph API 中适用于 Microsoft Entra 角色及组的 PIM，以及 ARM API 中适用于 Azure 资源的 PIM
这是 PIM API 的最终迭代。 其中包括：
- Microsoft Graph API 中适用于 Microsoft Entra 角色的 PIM - 正式版。
- ARM API 中 Azure 资源的 PIM - 正式发布。
- Microsoft Graph API 中组的 PIM - 预览版。
- Microsoft Graph API 中适用于 Microsoft Entra 角色的 PIM 警报 - 预览版。
- ARM API 中 Azure 资源的 PIM 警报 - 预览版。
Microsoft Graph API 中适用于 Microsoft Entra 角色的 PIM 以及 ARM API 中适用于 Azure 资源的 PIM 可提供一些优势，包括：
- PIM API 与适用于 Microsoft Entra 角色和 Azure 资源角色的常规角色分配 API 一致。
- 减少调用其他 PIM API 以加入资源、获取资源或获取角色定义的需求。
- 支持仅限应用权限。
- 新增功能，如审批和电子邮件通知配置。
PIM API 迭代 3 概述
跨提供程序（Microsoft Graph API 和 ARM API）的 PIM API 遵循相同的原则。
分配管理
要创建分配（活动或符合条件的）、续订、延长、更新分配（活动或符合条件的）、激活符合条件的分配、停用符合条件的分配，请使用资源 *AssignmentScheduleRequest 和 *EligibilityScheduleRequest：
- 对于 Microsoft Entra 角色：使用 unifiedRoleAssignmentScheduleRequest、unifiedRoleEligibilityScheduleRequest；
- 对于 Azure 资源：角色分配计划请求、角色资格计划请求；
- 对于组：privilegedAccessGroupAssignmentScheduleRequest、privilegedAccessGroupEligibilityScheduleRequest。
创建 *AssignmentScheduleRequest 或 *EligibilityScheduleRequest 对象可能会导致创建只读 *AssignmentSchedule、*EligibilitySchedule、*AssignmentScheduleInstance 和 *EligibilityScheduleInstance 对象。
- *AssignmentSchedule 和 *EligibilitySchedule 对象显示当前分配以及要在将来创建的分配的请求。
- *AssignmentScheduleInstance 和 *EligibilityScheduleInstance 对象仅显示当前分配。
在激活符合条件的分配时（调用了 Create*AssignmentScheduleRequest）， *EligibilityScheduleInstance 会继续存在，并将在激活的持续时间内创建新的 *AssignmentSchedule 和 *AssignmentScheduleInstance 对象。
有关分配和激活 API 的详细信息，请参阅用于管理角色分配和资格的 PIM API。
PIM 策略（角色设置）
要管理 PIM 策略，请使用 *roleManagementPolicy 和 *roleManagementPolicyAssignment 实体：
- 对于适用于 Microsoft Entra 角色的 PIM 和适用于组的 PIM：使用 unifiedroleManagementPolicy、unifiedroleManagementPolicyAssignment
- 对于适用于 Azure 资源的 PIM：角色管理策略、角色管理策略分配
*roleManagementPolicy 资源包括构成 PIM 策略的规则：审批要求、最大激活持续时间、通知设置等。
*roleManagementPolicyAssignment 对象会将策略附加到特定角色。
有关策略设置 API 的详细信息，请参阅角色设置和 PIM。
权限
适用于 Microsoft Entra 角色的 PIM
有关适用于 Microsoft Entra 角色的 PIM 所需的 Graph API 权限，请参阅角色管理权限。
适用于 Azure 资源的 PIM
适用于 Azure 资源角色的 PIM API 是在 Azure 资源管理器框架上开发的。 用户需要同意 Azure 资源管理，但不需要任何 Microsoft Graph API 权限。 还需要确保调用 API 的用户或服务主体在尝试管理的资源上至少具有所有者或用户访问管理员角色。
适用于组的 PIM
有关适用于组的 PIM 所需的图形 API 权限，请参阅适用于组的 PIM - 权限和特权。
PIM 实体与角色分配实体之间的关系
PIM 实体与适用于 Microsoft Entra 角色或 Azure 角色的持久（活动）分配的角色分配实体之间的唯一链接是 *AssignmentScheduleInstance。 这两个实体之间是一对一的映射关系。 该映射意味着 roleAssignment 和 *AssignmentScheduleInstance 都将包括：
- PIM 外部进行的永久性（活动）分配
- 使用 PIM 内部进行的计划的永久性（活动）分配
- 已激活的合格分配
PIM 特定的属性（如结束时间）只能通过 *AssignmentScheduleInstance 对象提供。