创建 roleEligibilityScheduleRequests

  • 项目

命名空间：microsoft.graph

重要

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

创建新的 unifiedRoleEligibilityScheduleRequest 对象。 此操作允许管理员和符合条件的用户添加、撤销或扩展符合条件的分配。

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

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

权限

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

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

对于委托方案，还必须至少为已登录用户分配以下Microsoft Entra角色之一：

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

HTTP 请求

POST /roleManagement/directory/roleEligibilityScheduleRequests

请求标头

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

请求正文

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

下表显示了创建 unifiedRoleEligibilityScheduleRequest 时的可选属性和必需属性。

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

响应

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

示例

示例 1：管理员分配角色资格计划请求

在以下请求中，管理员创建一个请求，将由 fdd7a751-b60b-444a-984c-02652fe8fa1c 标识的角色的资格分配给由 ID07706ff1-46c7-4847-ae33-3003830675a1 标识的主体。资格范围是 2022 年 6 月 30 日 UTC 时间午夜之前租户中的所有目录对象。

请求

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

{
  "action": "AdminAssign",
  "justification": "Assign User Admin eligibility 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": {
      "endDateTime": "2022-06-30T00:00:00Z",
      "type": "AfterDateTime"
    }
  }
}

响应

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleEligibilityScheduleRequests/$entity",
    "id": "672c03bf-226a-42ec-a8b7-3bfab96064a1",
    "status": "Provisioned",
    "createdDateTime": "2021-07-26T18:08:03.1299669Z",
    "completedDateTime": "2021-07-26T18:08:06.2081758Z",
    "approvalId": null,
    "customData": null,
    "action": "AdminAssign",
    "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "672c03bf-226a-42ec-a8b7-3bfab96064a1",
    "justification": "Assign User Admin eligibility to IT Helpdesk (User) group",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-07-26T18:08:06.2081758Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDateTime",
            "endDateTime": "2022-06-30T00:00:00Z",
            "duration": null
        }
    },
    "ticketInfo": {
        "ticketNumber": null,
        "ticketSystem": null
    }
}

示例 2：管理员删除现有角色资格计划请求

在以下请求中，管理员创建一个请求，以撤销由 fdd7a751-b60b-444a-984c-02652fe8fa1c 标识的角色对 ID07706ff1-46c7-4847-ae33-3003830675a1 标识的主体的资格。

请求

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

{
    "action": "AdminRemove",
    "justification": "Assign User Admin eligibility to IT Helpdesk (User) group",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
    "scheduleInfo": {
        "startDateTime": "2021-07-26T18:08:06.2081758Z",
        "expiration": {
            "endDateTime": "2022-06-30T00:00:00Z",
            "type": "AfterDateTime"
        }
    }
}

响应

以下示例显示了相应的响应。 请求返回一个响应对象，该对象将以前符合条件的分配的状态更改为 Revoked。 主体将不再看到其以前符合条件的角色。

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleEligibilityScheduleRequests/$entity",
    "id": "7f88a144-f9a9-4f8c-9623-39c321ae93c2",
    "status": "Revoked",
    "createdDateTime": "2021-08-06T17:59:12.4263499Z",
    "completedDateTime": null,
    "approvalId": null,
    "customData": null,
    "action": "AdminRemove",
    "principalId": "07706ff1-46c7-4847-ae33-3003830675a1",
    "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": null,
    "justification": "Assign User Admin eligibility to IT Helpdesk (User) group",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-07-26T18:08:06.2081758Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDateTime",
            "endDateTime": "2022-06-30T00:00:00Z",
            "duration": null
        }
    },
    "ticketInfo": {
        "ticketNumber": null,
        "ticketSystem": null
    }
}