创建 historyDefinitions

  • 项目

命名空间：microsoft.graph

创建新的 accessReviewHistoryDefinition 对象。

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

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

权限

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

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

对于委托方案，已登录用户必须至少具有以下Microsoft Entra角色之一。

编写组或应用的访问评审 编写Microsoft Entra角色的访问评审
用户管理员
标识治理管理员		 标识治理管理员
特权角色管理员

HTTP 请求

POST /identityGovernance/accessReviews/historyDefinitions

请求标头

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

请求正文

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

下表显示了用于创建 accessReviewHistoryDefinition 的必需属性。

属性 类型 说明
displayName String 访问评审历史记录数据收集的名称。 必填。
reviewHistoryPeriodStartDateTime DateTimeOffset 时间戳。 从此日期开始或之后的评审将包含在提取的历史记录数据中。 仅当未定义 scheduleSettings 时才需要。
reviewHistoryPeriodEndDateTime DateTimeOffset 时间戳。 从此日期开始或之前开始的审阅将包含在提取的历史记录数据中。 仅当未定义 scheduleSettings 时才需要。
scopes accessReviewQueryScope 集合 用于筛选提取的历史记录数据中包含的评审。 提取其范围与此提供的范围匹配的评审。 必填。
有关详细信息，请参阅 accessReviewHistoryDefinition 支持的范围查询。
scheduleSettings accessReviewHistoryScheduleSettings 尚不支持。 定期访问评审历史记录定义系列的设置。 仅当未定义 reviewHistoryPeriodStartDateTime 或 reviewHistoryPeriodEndDateTime 时才需要。

accessReviewHistoryDefinition 支持的范围查询

accessReviewHistoryDefinition 的 scopes 属性基于 accessReviewQueryScope，该资源允许在查询属性中配置不同的资源。 然后，这些资源表示历史记录定义的范围，并指定在创建历史记录定义的 accessReviewHistoryInstances 时生成的可下载 CSV 文件中包含的审阅历史记录数据的类型。

$filteraccessReviewScheduleDefinition 的 scope 属性支持使用 contains 运算符的查询参数。 对请求使用以下格式：

/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, '{object}')

可以 {object} 具有以下值之一：

值 说明
/groups 列出单个组的每个 accessReviewScheduleDefinition (不包括作用域为来宾) 的所有 Microsoft 365 组的定义。
/groups/{group id} 列出特定组的每个 accessReviewScheduleDefinition (不包括限定为来宾) 的所有 Microsoft 365 组的定义。
./members 列出每个 accessReviewScheduleDefinition 作用域为包含来宾的所有 Microsoft 365 组。
accessPackageAssignments 列出访问包上的每个 accessReviewScheduleDefinition。
roleAssignmentScheduleInstances 列出分配给特权角色的主体的每个 accessReviewScheduleDefinition。

$filteraccessReviewInactiveUserQueryScope 或 principalResourceMembershipScope 不支持查询参数。

响应

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

示例

以下示例演示如何创建访问评审历史记录定义，该定义的范围限定为访问包和组的访问评审，该定义在开始日期 01/01/2021 和结束日期 04/05/2021 之间运行。

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/historyDefinitions
Content-Type: application/json

{
  "displayName": "Last quarter's group reviews April 2021",
  "decisions": [
    "approve",
    "deny",
    "dontKnow",
    "notReviewed",
    "notNotified"
  ],
  "reviewHistoryPeriodStartDateTime": "2021-01-01T00:00:00Z",
  "reviewHistoryPeriodEndDateTime": "2021-04-30T23:59:59Z",
  "scopes": [
    {
      "@odata.type": "#microsoft.graph.accessReviewQueryScope",
      "queryType": "MicrosoftGraph",     
      "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, 'accessPackageAssignments')",
      "queryRoot": null
    },  
    {
      "@odata.type": "#microsoft.graph.accessReviewQueryScope",
      "queryType": "MicrosoftGraph",     
      "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, '/groups')",
      "queryRoot": null
    }
  ]
}

响应

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

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

{
    "@odata.type": "#microsoft.graph.accessReviewHistoryDefinition",
    "id": "b2cb022f-b7e1-40f3-9854-c65a40861c38",
    "displayName": "Last quarter's group reviews April 2021",
    "reviewHistoryPeriodStartDateTime": "2021-01-01T00:00:00Z",
    "reviewHistoryPeriodEndDateTime": "2021-04-30T23:59:59Z",
    "decisions": [
        "approve",
        "deny",
        "dontKnow",
        "notReviewed",
        "notNotified"
    ],
    "status": "requested",
    "createdDateTime": "2021-04-14T00:22:48.9392594Z",
    "createdBy": {
        "id": "957f1027-c0ee-460d-9269-b8444459e0fe",
        "displayName": "MOD Administrator",
        "userPrincipalName": "admin@contoso.com"
    },
    "scopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "queryType": "MicrosoftGraph",
            "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, 'accessPackageAssignments')",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "queryType": "MicrosoftGraph",
            "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, '/groups')",
            "queryRoot": null
        }
    ]
}