Crear historyDefinitions

  • Artículo

Espacio de nombres: microsoft.graph

Cree un nuevo objeto accessReviewHistoryDefinition .

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) AccessReview.ReadWrite.All No disponible.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación AccessReview.ReadWrite.All No disponible.

Para escenarios delegados, el usuario que ha iniciado sesión debe tener al menos uno de los siguientes roles de Microsoft Entra.

Escribir revisiones de acceso de un grupo o aplicación Escribir revisiones de acceso de un rol de Microsoft Entra
Administrador de usuarios
Administrador de gobernanza de identidades		 Administrador de roles con privilegios de administrador
de gobernanza de identidades

Solicitud HTTP

POST /identityGovernance/accessReviews/historyDefinitions

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Type application/json. Obligatorio.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON del objeto accessReviewHistoryDefinition .

En la tabla siguiente se muestran las propiedades necesarias que se usan para crear un accessReviewHistoryDefinition.

Propiedad Tipo Descripción
displayName Cadena Nombre de la recopilación de datos del historial de revisión de acceso. Obligatorio.
reviewHistoryPeriodStartDateTime DateTimeOffset Marca de tiempo. Las revisiones a partir de esta fecha o después se incluirán en los datos del historial capturados. Solo es necesario si scheduleSettings no está definido.
reviewHistoryPeriodEndDateTime DateTimeOffset Marca de tiempo. Las revisiones a partir de o antes de esta fecha se incluirán en los datos del historial capturado. Solo es necesario si scheduleSettings no está definido.
ámbitos colección accessReviewQueryScope Se usa para filtrar qué revisiones se incluyen en los datos del historial capturado. Captura las revisiones cuyo ámbito coincide con este ámbito proporcionado. Obligatorio.
Para obtener más información, vea Consultas de ámbito admitidas para accessReviewHistoryDefinition.
scheduleSettings accessReviewHistoryScheduleSettings Todavía no se admite. La configuración de una serie de definiciones periódicas del historial de revisión de acceso. Solo es necesario si reviewHistoryPeriodStartDateTime o reviewHistoryPeriodEndDateTime no están definidos .

Consultas de ámbito admitidas para accessReviewHistoryDefinition

La propiedad scopes de accessReviewHistoryDefinition se basa en accessReviewQueryScope, un recurso que permite configurar diferentes recursos en su propiedad de consulta . A continuación, estos recursos representan el ámbito de la definición del historial y dictan el tipo de datos del historial de revisión que se incluyen en el archivo CSV descargable que se genera cuando se crea accessReviewHistoryInstances de la definición de historial.

El $filter parámetro de consulta con el contains operador se admite en la propiedad scope de accessReviewScheduleDefinition. Use el formato siguiente para la solicitud:

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

{object} puede tener uno de los siguientes valores:

Valor Descripción
/groups Enumera cada accessReviewScheduleDefinition en grupos individuales (excluye las definiciones con ámbito a todos los grupos de Microsoft 365 con invitados).
/groups/{group id} Enumere cada accessReviewScheduleDefinition en un grupo específico (excluye las definiciones con ámbito a todos los grupos de Microsoft 365 con invitados).
./members Enumere cada accessReviewScheduleDefinition con ámbito para todos los grupos de Microsoft 365 con invitados.
accessPackageAssignments Enumere cada accessReviewScheduleDefinition en un paquete de acceso.
roleAssignmentScheduleInstances Enumere cada accessReviewScheduleDefinition para las entidades de seguridad asignadas a un rol con privilegios.

El $filter parámetro de consulta no se admite en accessReviewInactiveUserQueryScope o principalResourceMembershipScope.

Respuesta

Si se ejecuta correctamente, este método devuelve un 201 Created código de respuesta y un objeto accessReviewHistoryDefinition en el cuerpo de la respuesta.

Ejemplos

En el ejemplo siguiente se muestra cómo crear una definición del historial de revisión de acceso con ámbito para acceder a revisiones en paquetes y grupos de acceso, que se ejecuta entre la fecha de inicio del 01/01/2021 y la fecha de finalización del 04/05/2021.

Solicitud

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
    }
  ]
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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
        }
    ]
}