Share via


Criar historyDefinitions

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie um novo objeto accessReviewHistoryDefinition .

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) AccessReview.ReadWrite.All Indisponível.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Aplicativo AccessReview.ReadWrite.All Indisponível.

Para cenários delegados, o usuário conectado deve ter pelo menos uma das seguintes funções de Microsoft Entra.

Gravar revisões de acesso de um grupo ou aplicativo Escrever revisões de acesso de uma função de Microsoft Entra
Administrador do usuário
Administrador de Governança de Identidade
Administrador de funções privilegiadas do administrador
de governança de identidade

Solicitação HTTP

POST /identityGovernance/accessReviews/historyDefinitions

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON do objeto accessReviewHistoryDefinition .

A tabela a seguir mostra as propriedades necessárias usadas para criar um accessReviewHistoryDefinition.

Propriedade Tipo Descrição
displayName Cadeia de caracteres Nome da coleção de dados de histórico de revisão de acesso. Obrigatório.
reviewHistoryPeriodStartDateTime DateTimeOffset Um carimbo de data/hora. As revisões que começam em ou após essa data estão nos dados de histórico buscados. Necessário apenas se agendaSettings não estiverem definidos.
reviewHistoryPeriodEndDateTime DateTimeOffset Um carimbo de data/hora. As revisões que começam ou antes dessa data são incluídas nos dados de histórico buscados. Necessário apenas se agendaSettings não estiverem definidos.
escopos coleção accessReviewQueryScope Usado para filtrar quais revisões estão incluídas nos dados de histórico buscados. Busca revisões cujo escopo corresponde a esse escopo fornecido. Obrigatório.
Para saber mais, confira Consultas de escopo com suporte para accessReviewHistoryDefinition.
scheduleSettings accessReviewHistoryScheduleSettings Ainda não há suporte. As configurações de uma série de definição de histórico de revisão de acesso recorrente. Necessário apenas se reviewHistoryPeriodStartDateTime ou reviewHistoryPeriodEndDateTime não estiver definido.

Consultas de escopo com suporte para accessReviewHistoryDefinition

O $filter parâmetro de consulta com o contains operador tem suporte na propriedade de escopo do accessReviewScheduleDefinition. Use o seguinte formato para a solicitação:

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

O {object} pode ter um dos seguintes valores:

Valor Descrição
/groups Liste cada accessReviewScheduleDefinition em grupos individuais (exclui definições em escopo para todos os grupos do Microsoft 365 com convidados).
/groups/{group id} Liste cada accessReviewScheduleDefinition em um grupo específico (exclui definições com escopo para todos os grupos do Microsoft 365 com convidados).
./members Liste cada accessReviewScheduleDefinition com escopo para todos os grupos do Microsoft 365 com convidados.
accessPackageAssignments Liste cada accessReviewScheduleDefinition em um pacote de acesso.
roleAssignmentScheduleInstances Liste cada accessReviewScheduleDefinition para entidades atribuídas a uma função privilegiada.

O $filter parâmetro de consulta não tem suporte no accessReviewInactiveUserQueryScope ou principalResourceMembershipScope.

Resposta

Se for bem-sucedido, esse método retornará um 201 Created código de resposta e um objeto accessReviewHistoryDefinition no corpo da resposta.

Exemplos

O exemplo a seguir mostra como criar uma definição de histórico de revisão de acesso com escopo para acessar revisões em pacotes e grupos de acesso, em execução entre a data de início de 01/01/2021 e a data de término de 04/05/2021.

Solicitação

POST https://graph.microsoft.com/beta/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
    }
  ]
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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