通过

创建 roleAssignmentScheduleRequests

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

创建新的 unifiedRoleAssignmentScheduleRequest 对象。 此操作允许管理员和用户添加、删除、延长或续订分配。 若要运行此请求，调用用户必须具有多重身份验证 () 强制实施 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 时所需的属性。

属性 类型 说明
id String unifiedRoleAssignmentScheduleRequest 的唯一标识符。 键，不可为 null，只读。
action String 表示对角色分配的操作的类型。 可能的值有：
  • AdminAssign：供管理员将角色分配给用户或组。
  • AdminRemove：供管理员从角色中删除用户或组。
  • AdminUpdate：供管理员更改现有角色分配。
  • AdminExtend：供管理员延长即将到期的工作分配。
  • AdminRenew：供管理员续订过期的分配。
  • SelfActivate：供用户激活其分配。
  • SelfDeactivate：让用户停用其活动分配。
  • SelfExtend：供用户请求延长其即将到期的分配。
  • SelfRenew：供用户请求续订其过期分配。
principalId String 向其授予工作分配的主体的标识符。
roleDefinitionId String 分配所针对的 unifiedRoleDefinition 的标识符。 只读。
directoryScopeId String 表示分配范围的目录对象的标识符。 分配的范围确定已向其授予主体访问权限的资源集。 目录范围是存储在目录中的共享范围，可由多个应用程序理解。 用于 / 租户范围。 使用 appScopeId 将范围限制为仅应用程序。
appScopeId String 当分配范围特定于应用时，特定于应用的范围的标识符。 分配的范围确定已向其授予主体访问权限的资源集。 应用范围是仅此应用程序定义和理解的范围。 用于 / 租户范围的应用范围。 使用 directoryScopeId 将范围限制为特定的目录对象，例如管理单元。
isValidationOnly 布尔值 指定调用是验证还是实际调用。 仅当想要在实际提交请求之前检查激活是否受其他规则（如 MFA）的约束时，才设置此属性。
targetScheduleId String 附加到分配的计划对象的 ID。
理由 String 用户和管理员在创建请求时提供的消息，说明为何需要该请求。
scheduleInfo requestSchedule 角色分配请求的计划对象。
ticketInfo ticketInfo 附加到角色分配请求的 ticketInfo 对象，其中包括票证编号和票证系统的详细信息。

响应

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

当调用用户在登录会话期间未受到多重身份验证的质询时，使用 SelfActivate 操作的请求将失败并返回 400 Bad request 响应代码。

示例

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

请求

在以下请求中，管理员创建一个请求，将标识的角色 fdd7a751-b60b-444a-984c-02652fe8fa1c 分配给由 ID07706ff1-46c7-4847-ae33-3003830675a1 标识的主体。其角色的范围是租户中的所有目录对象，分配是永久的，即不会过期。

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

{
  "action": "AdminAssign",
  "justification": "Assign User Admin to IT Helpdesk (User) group",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
  "scheduleInfo": {
    "startDateTime": "2021-07-01T00:00:00Z",
    "expiration": {
      "type": "NoExpiration"
    }
  }
}

响应

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
  "id": "b5a22921-656a-4429-9c4e-59a5f576614d",
  "status": "Provisioned",
  "createdDateTime": "2021-07-27T09:18:40.2029365Z",
  "completedDateTime": "2021-07-27T09:18:42.7811184Z",
  "approvalId": null,
  "customData": null,
  "action": "AdminAssign",
  "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "appScopeId": null,
  "isValidationOnly": false,
  "targetScheduleId": "b5a22921-656a-4429-9c4e-59a5f576614d",
  "justification": "Assign User Admin to IT Helpdesk (User) group",
  "createdBy": {
    "application": null,
    "device": null,
    "user": {
      "displayName": null,
      "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f"
    }
  },
  "scheduleInfo": {
    "startDateTime": "2021-07-27T09:18:42.7811184Z",
    "recurrence": null,
    "expiration": {
      "type": "noExpiration",
      "endDateTime": null,
      "duration": null
    }
  },
  "ticketInfo": {
    "ticketNumber": null,
    "ticketSystem": null
  }
}

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

请求

在以下请求中， principalIdc6ad1942-4afa-47f8-8d48-afb5d8d69d2f 标识的用户激活由 标识 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3的自己的合格角色。 其角色的范围是租户中的所有目录对象，分配时间为 5 小时。 若要运行此请求，调用用户必须具有多重身份验证 () 强制实施 MFA，并在向其提出 MFA 质询的会话中运行查询。

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

{
    "action": "SelfActivate",
    "principalId": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f",
    "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
    "directoryScopeId": "/",
    "justification": "Need to update app roles for selected apps.",
    "scheduleInfo": {
        "startDateTime": "2021-08-17T17:40: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/beta/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "163daf73-8746-4996-87de-ab71dc624bf9",
    "status": "Granted",
    "createdDateTime": "2021-08-17T17:39:36.7040696Z",
    "completedDateTime": "2021-08-17T17:40:00Z",
    "approvalId": null,
    "customData": null,
    "action": "SelfActivate",
    "principalId": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f",
    "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "163daf73-8746-4996-87de-ab71dc624bf9",
    "justification": "Need to update app roles for selected apps.",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "c6ad1942-4afa-47f8-8d48-afb5d8d69d2f"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-08-17T17:40:00Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Normal-67890",
        "ticketSystem": "MS Project"
    }
}