创建 roleAssignmentScheduleRequests

命名空间:microsoft.graph

在 PIM 中,通过 unifiedRoleAssignmentScheduleRequest 对象执行以下操作:

  • 请求主体的活动和持久角色分配,有或没有到期日期。
  • 激活、停用、延长或续订主体的合格角色分配。

若要调用此 API 来为自己更新、续订和扩展分配,必须具有多重身份验证 (MFA) 强制实施,并在会话中运行查询,在该会话中对 MFA 进行质询。 请参阅 启用每用户Microsoft Entra 多重身份验证来保护登录事件

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) RoleAssignmentSchedule.ReadWrite.Directory RoleAssignmentSchedule.Remove.Directory、RoleEligibilitySchedule.Remove.Directory、RoleManagement.ReadWrite.Directory
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 RoleAssignmentSchedule.ReadWrite.Directory RoleManagement.ReadWrite.Directory、RoleAssignmentSchedule.Remove.Directory、RoleEligibilitySchedule.Remove.Directory

在具有工作或学校帐户的委托方案中,必须为登录用户分配受支持的 Microsoft Entra 角色 或具有支持的角色权限的自定义角色。 此操作支持以下最低特权角色。

  • 对于读取操作:全局读取者、安全操作员、安全读取者、安全管理员或特权角色管理员
  • 对于写入操作:特权角色管理员

HTTP 请求

POST /roleManagement/directory/roleAssignmentScheduleRequests

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-Type application/json. 必需。

请求正文

在请求正文中,提供 unifiedRoleAssignmentScheduleRequest 对象的 JSON 表示形式。

创建 unifiedRoleAssignmentScheduleRequest 时,可以指定以下属性。

属性 类型 说明
action unifiedRoleScheduleRequestActions 表示对角色分配请求的操作类型。 可取值包括:adminAssignadminUpdateadminRemoveselfActivateselfDeactivateadminExtendadminRenewselfExtendselfRenewunknownFutureValue
  • adminAssign:供管理员将角色分配给用户或组。
  • adminRemove:供管理员从角色中删除用户或组。
  • adminUpdate:供管理员更改现有角色分配。
  • adminExtend:供管理员延长即将到期的工作分配。
  • adminRenew:供管理员续订过期的分配。
  • selfActivate:供用户激活其分配。
  • selfDeactivate:让用户停用其活动分配。
  • selfExtend:供用户请求延长其即将到期的分配。
  • selfRenew:供用户请求续订其过期分配。
customData String 用于定义请求的任何自定义数据的自由文本字段。 可选。
principalId String 已授予分配的主体的标识符。 必填。
roleDefinitionId String 要分配的 unifiedRoleDefinition 对象的标识符。 必填。
directoryScopeId String 表示分配范围的目录对象的标识符。 分配的范围确定已向其授予主体访问权限的资源集。 目录范围是存储在目录中的共享范围,可由多个应用程序理解。 用于 / 租户范围。 使用 appScopeId 将范围限制为仅应用程序。 需要 directoryScopeIdappScopeId
appScopeId String 分配范围限定为应用时,特定于应用的范围的标识符。 分配的范围确定已向其授予主体访问权限的资源集。 应用范围是仅此应用程序定义和理解的范围。 用于 / 租户范围的应用范围。 使用 directoryScopeId 将范围限制为特定的目录对象,例如管理单元。 需要 directoryScopeIdappScopeId
理由 String 用户和管理员在创建 unifiedRoleAssignmentScheduleRequest 对象时提供的消息。

adminRemove 操作可选selfDeactivate;对于其他操作类型,可能是可选的,也可能是必需操作类型,具体取决于链接到 Microsoft Entra 角色的策略中的规则。 有关详细信息,请参阅 PIM 中的规则
scheduleInfo requestSchedule 角色分配请求的时间段。 目前不支持定期计划。 必填。
ticketInfo ticketInfo 链接到角色分配请求的票证详细信息,包括票证编号和票证系统的详细信息。

adminRemove 操作可选selfDeactivate;对于其他操作类型,可能是可选的,也可能是必需操作类型,具体取决于链接到 Microsoft Entra 角色的策略中的规则。 有关详细信息,请参阅 PIM 中的规则

响应

如果成功,此方法在 201 Created 响应正文中返回响应代码和 unifiedRoleAssignmentScheduleRequest 对象。

示例

示例 1:向主体分配目录角色的管理员

在以下请求中,管理员创建一个请求,将标识 fdd7a751-b60b-444a-984c-02652fe8fa1c 的角色分配给 ID 071cc716-8147-4397-a5ba-b2105951cc0b标识的主体。 其角色的范围是租户中的所有目录对象,并且分配是永久性的。

请求

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests
Content-Type: application/json

{
    "action": "adminAssign",
    "justification": "Assign Groups Admin to IT Helpdesk group",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "scheduleInfo": {
        "startDateTime": "2022-04-10T00:00:00Z",
        "expiration": {
            "type": "NoExpiration"
        }
    }
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
    "status": "Provisioned",
    "createdDateTime": "2022-04-11T11:50:03.9014347Z",
    "completedDateTime": "2022-04-11T11:50:05.9999343Z",
    "approvalId": null,
    "customData": null,
    "action": "adminAssign",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "95c690fb-3eb3-4942-a03f-4524aed6f31e",
    "justification": "Assign Groups Admin to IT Helpdesk group",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2022-04-11T11:50:05.9999343Z",
        "recurrence": null,
        "expiration": {
            "type": "noExpiration",
            "endDateTime": null,
            "duration": null
        }
    },
    "ticketInfo": {
        "ticketNumber": null,
        "ticketSystem": null
    }
}

示例 2:用户激活其符合条件的角色

请求

在以下请求中, 由 principalId071cc716-8147-4397-a5ba-b2105951cc0b 标识的用户将自己的 合格角色 激活为由 ID 8424c6f0-a189-499e-bbd0-26c1753c96d4标识的 Microsoft Entra 角色。 其角色的范围是租户中的所有目录对象,分配时间为 5 小时。 若要运行此请求,调用用户必须具有多重身份验证 () 强制实施 MFA,并在向其提出 MFA 质询的会话中运行查询。

若要检索其资格请求的详细信息并确定激活资格,用户将调用 unifiedRoleEligibilitySchedule: filterByCurrentUser API。

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests/
Content-Type: application/json

{
    "action": "selfActivate",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "justification": "I need access to the Attribute Administrator role to manage attributes to be assigned to restricted AUs",
    "scheduleInfo": {
        "startDateTime": "2022-04-14T00:00:00.000Z",
        "expiration": {
            "type": "AfterDuration",
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "911bab8a-6912-4de2-9dc0-2648ede7dd6d",
    "status": "Granted",
    "createdDateTime": "2022-04-13T08:52:32.6485851Z",
    "completedDateTime": "2022-04-14T00:00:00Z",
    "approvalId": null,
    "customData": null,
    "action": "selfActivate",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "911bab8a-6912-4de2-9dc0-2648ede7dd6d",
    "justification": "I need access to the Attribute Administrator role to manage attributes to be assigned to restricted AUs",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2022-04-14T00:00:00Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}