Partilhar via

Criar definições

  • Artigo

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 accessReviewScheduleDefinition .

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ❌

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) AccessReview.ReadWrite.All Indisponível.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application AccessReview.ReadWrite.All Indisponível.

Importante

Em cenários delegados com contas escolares ou profissionais, o utilizador com sessão iniciada tem de ter uma função de Microsoft Entra suportada ou uma função personalizada com uma permissão de função suportada. As seguintes funções com menos privilégios são suportadas para esta operação.

  • Para escrever revisões de acesso de um grupo ou aplicação: Administrador de Utilizadores, Administrador de Governação de Identidades
  • Para escrever revisões de acesso de uma função de Microsoft Entra: Administrador de Governação de Identidades, Administrador de Funções Com Privilégios

Solicitação HTTP

POST /identityGovernance/accessReviews/definitions

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 do pedido, forneça uma representação JSON de um objeto accessReviewScheduleDefinition .

A tabela seguinte mostra as propriedades aceites para criar um accessReview.

Propriedade Tipo Descrição
additionalNotificationRecipients accessReviewNotificationRecipientItem collection (coleção accessReviewNotificationRecipientItem ) Define a lista de utilizadores ou membros do grupo adicionais a notificar sobre o progresso da revisão de acesso.
descriptionForAdmins Cadeia de caracteres Contexto da revisão fornecida aos administradores. Obrigatório.
descriptionForReviewers Cadeia de caracteres Contexto da revisão fornecida aos revisores no notificações por email. Email notificações suportam até 256 carateres. Obrigatório.
displayName Cadeia de caracteres Nome da série de revisão de acesso. Obrigatório.
fallbackReviewers accessReviewReviewerScope collection (coleção accessReviewReviewerScope ) Se for fornecido, os revisores de contingência serão convidados a concluir uma revisão se os revisores primários não existirem. Por exemplo, se os gestores estiverem selecionados como reviewers e um principal em análise não tiver um gestor no Microsoft Entra ID, é pedido aos revisores de contingência que revejam esse principal.

NOTA: O valor desta propriedade será ignorado se os revisores de contingência forem atribuídos através da propriedade stageSettings .
instanceEnumerationScope accessReviewScope No caso de uma revisão de todos os grupos, isto determina o âmbito de que grupos serão revistos. Veja accessReviewScope e saiba também como configurar o âmbito da definição de revisão de acesso.
revisores accessReviewReviewerScope collection (coleção accessReviewReviewerScope ) Define quem são os revisores. Se não forem especificadas nenhuma, a revisão é uma revisão automática (os utilizadores revêm o seu próprio acesso). Para obter exemplos de opções para atribuir revisores, consulte Atribuir revisores à definição de revisão de acesso com o microsoft API do Graph.

NOTA: O valor desta propriedade será ignorado se os revisores forem atribuídos através da propriedade stageSettings .
scope accessReviewScope Define as entidades cujo acesso é revisto. Veja accessReviewScope e saiba também como configurar o âmbito da definição de revisão de acesso. Obrigatório.
stageSettings accessReviewStageSettings collection (coleção accessReviewStageSettings) Define quantas fases cada instância de uma série de revisão de acesso terá. As fases serão criadas sequencialmente com base na propriedade dependsOn. Cada fase pode ter um conjunto diferente de revisores, revisores de contingência e definições.

Quando esta propriedade é definida, os respetivos valores são utilizados em vez dos valores correspondentes no objeto accessReviewScheduleDefinition e na respetiva propriedade settings . Opcional.
settings accessReviewScheduleSettings As definições de uma série de revisão de acesso. A periodicidade é determinada aqui. Veja accessReviewScheduleSettings.
backupReviewers (preterido) accessReviewReviewerScope collection (coleção accessReviewReviewerScope ) Esta propriedade foi substituída por fallbackReviewers. No entanto, especificar backupReviewers ou fallbackReviewers preenche automaticamente os mesmos valores para a outra propriedade.

Resposta

Se for bem-sucedido, este método devolve um 201 Created código de resposta e um objeto accessReviewScheduleDefinition no corpo da resposta.

Exemplos

Exemplo 1: Criar uma revisão de acesso num grupo

O exemplo seguinte cria uma revisão de acesso com as seguintes definições:

  • A revisão analisa todos os membros de um grupo com o ID02f3bafb-448c-487c-88c2-5fd65ce49a41.
  • Um utilizador específico com o ID398164b1-5196-49dd-ada2-364b49f99b27 de utilizador é o revisor.
  • Repete-se semanalmente e continua indefinidamente.

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Test create",
  "descriptionForAdmins": "New scheduled access review",
  "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "reviewers": [
    {
      "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
      "queryType": "MicrosoftGraph"
    }
  ],  
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": false,
    "defaultDecision": "None",
    "instanceDurationInDays": 1,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-09-08T12:02:30.667Z"
      }
    }
  }
}

Resposta

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

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

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Test create",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastModifiedDateTime": "0001-01-01T00:00:00Z",
  "status": "NotStarted",
  "descriptionForAdmins": "Test create",
  "descriptionForReviewers": "Test create",
  "instanceEnumerationScope": null,
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe",
    "displayName": "MOD Administrator",
    "userPrincipalName": "admin@contoso.com"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "reviewers": [
    {
      "query": "/users/7eae986b-d425-48b2-adf2-3c777f4444f3",
      "queryType": "MicrosoftGraph",
      "queryRoot": "decisions"
    }
  ],  
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": false,
    "defaultDecision": "None",
    "instanceDurationInDays": 1,
    "autoApplyDecisionsEnabled": false,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1,
        "month": 0,
        "dayOfMonth": 0,
        "daysOfWeek": [],
        "firstDayOfWeek": "sunday",
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "numberOfOccurrences": 0,
        "recurrenceTimeZone": null,
        "startDate": "2020-09-08",
        "endDate": null
      }
    },
  "applyActions": []
  },
  "additionalNotificationRecipients": []
}

Exemplo 2: Criar uma revisão de acesso em todas as equipas com utilizadores convidados inativos

O exemplo seguinte cria uma revisão de acesso com as seguintes definições:

  • A revisão analisa todas as equipas com utilizadores convidados inativos. O período de inatividade é de 30 dias a partir da data de início da revisão de acesso.
  • Os proprietários dos grupos são os revisores e os revisores de contingência são atribuídos.
  • Repete-se no terceiro dia de cada trimestre e continua indefinidamente.
  • autoApplyDecisionsEnabled está definido true como com a predefiniçãoDecisão definida como Deny.

Solicitação

No corpo do pedido, forneça uma representação JSON do objeto accessReviewScheduleDefinition .

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Review inactive guests on teams",
  "descriptionForAdmins": "Control guest user access to our teams.",
  "descriptionForReviewers": "Information security is everyone's responsibility. Review our access policy for more.",
  "instanceEnumerationScope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
    },
  "reviewers": [
    {
      "query": "./owners",
      "queryType": "MicrosoftGraph"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/users/fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
      "queryType": "MicrosoftGraph"
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "recommendationsEnabled": true,
    "instanceDurationInDays": 3,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "dayOfMonth": 5,
        "interval": 3
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-05-04T00:00:00.000Z"
      }
    },
    "defaultDecisionEnabled": true,
    "defaultDecision": "Deny",
    "autoApplyDecisionsEnabled": true
  }
}

Resposta

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

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
  "id": "b0966e21-a01e-43c9-8f8b-9ba30ed5710a",
  "displayName": "Review inactive guests on teams",
  "createdDateTime": "2021-05-04T18:27:02.6719849Z",
  "lastModifiedDateTime": "2021-05-04T18:27:24.0889623Z",
  "status": "InProgress",
  "descriptionForAdmins": "Control guest user access to our teams.",
  "descriptionForReviewers": "Information security is everyone's responsibility. Review our access policy for more.",
  "createdBy": {
    "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
    "displayName": "MOD Administrator",
    "userPrincipalName": "admin@contoso.com"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "queryRoot": null,
    "inactiveDuration": "P30D"
  },
  "instanceEnumerationScope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team'))&$count=true",
    "queryType": "MicrosoftGraph",
    "queryRoot": null
  },
  "reviewers": [
    {
      "query": "./owners",
      "queryType": "MicrosoftGraph",
      "queryRoot": null
    }
  ],
  "backupReviewers": [],
  "fallbackReviewers": [
    {
      "query": "/users/fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
      "queryType": "MicrosoftGraph",
      "queryRoot": null
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": true,
    "defaultDecision": "Deny",
    "instanceDurationInDays": 3,
    "autoApplyDecisionsEnabled": true,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "interval": 3,
        "month": 0,
        "dayOfMonth": 5,
        "daysOfWeek": [],
        "firstDayOfWeek": "sunday",
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "numberOfOccurrences": 0,
        "recurrenceTimeZone": null,
        "startDate": "2021-05-05",
        "endDate": null
      }
    },
    "applyActions": []
  },
  "additionalNotificationRecipients": []
}

Exemplo 3: Criar uma revisão de acesso de todos os utilizadores para uma aplicação

O exemplo seguinte cria uma revisão de acesso com as seguintes definições:

  • A revisão revê o acesso do utilizador a uma aplicação.
  • Os gestores de pessoas são os revisores e os revisores de contingência são membros de um grupo.
  • Repete-se semestralmente e termina 1 ano a partir do startDate.

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Review employee access to LinkedIn",
  "descriptionForAdmins": "Review employee access to LinkedIn",
  "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/users",
        "queryType": "MicrosoftGraph"
      }
    ],
    "resourceScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/servicePrincipals/bae11f90-7d5d-46ba-9f55-8112b59d92ae",
        "queryType": "MicrosoftGraph"
      }
    ]
  },
  "reviewers": [
    {
      "query": "./manager",
      "queryType": "MicrosoftGraph",
      "queryRoot": "decisions"
    }
  ],
  "backupReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
      "queryType": "MicrosoftGraph"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
      "queryType": "MicrosoftGraph"
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": true,
    "defaultDecision": "Recommendation",
    "instanceDurationInDays": 180,
    "autoApplyDecisionsEnabled": true,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "interval": 6,
        "dayOfMonth": 0
      },
      "range": {
        "type": "numbered",
        "startDate": "2021-05-05",
        "endDate": "2022-05-05"
      }
    }
  }
}

Resposta

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

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
  "id": "1f79f34b-8667-40d9-875c-893b630b3dec",
  "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/users"
      }
    ],
    "resourceScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/servicePrincipals/bae11f90-7d5d-46ba-9f55-8112b59d92ae"
      }
    ]
  },
  "reviewers": [
    {
      "query": "./manager"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers"
    }
  ]
}

Exemplo 4: Criar uma revisão de acesso num grupo com várias fases

O exemplo seguinte cria uma revisão de acesso com as seguintes definições:

  • A revisão analisa todos os membros de um grupo com o ID02f3bafb-448c-487c-88c2-5fd65ce49a41.
  • Tem duas fases:
    • Um utilizador específico com o ID398164b1-5196-49dd-ada2-364b49f99b27 de utilizador é o revisor da primeira fase.
    • Os gestores de pessoas são os revisores e revisores de contingência para a segunda fase.
  • Repete-se semanalmente e continua indefinidamente.

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Group Multi-stage Access Review",
  "descriptionForAdmins": "New scheduled access review",
  "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "stageSettings": [
    {
      "stageId": "1",
      "durationInDays": 2,
      "recommendationsEnabled": false,
      "decisionsThatWillMoveToNextStage": [
          "NotReviewed",
          "Approve"
      ],
      "reviewers": [
        {
          "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
          "queryType": "MicrosoftGraph"
        }
      ]
    },
    {
      "stageId": "2",
      "dependsOn": [
          "1"
      ],
      "durationInDays": 2,
      "recommendationsEnabled": true,
      "reviewers": [
        {
          "query": "./manager",
          "queryType": "MicrosoftGraph",
          "queryRoot": "decisions"
        }
      ],
      "fallbackReviewers": [
        {
          "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
          "queryType": "MicrosoftGraph"
        }
      ]
    }
  ],
  "settings": {
    "instanceDurationInDays": 4,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-09-08T12:02:30.667Z"
      }
    },
    "decisionHistoriesForReviewersEnabled": true
  }
}

Resposta

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

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

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Group Multi-stage Access Review",
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers"
  },
  "stageSettings": [
    {
      "stageId": "1",
      "durationInDays": 2,
      "recommendationsEnabled": false,
      "decisionsThatWillMoveToNextStage": [
          "NotReviewed",
          "Approve"
      ],
      "reviewers": [
        {
          "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
          "queryType": "MicrosoftGraph"
        }
      ]
    },
    {
      "stageId": "2",
      "dependsOn": [
          "1"
      ],
      "durationInDays": 2,
      "recommendationsEnabled": true,
      "reviewers": [
        {
          "query": "./manager",
          "queryType": "MicrosoftGraph",
          "queryRoot": "decisions"
        }
      ],
      "fallbackReviewers": [
        {
          "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
          "queryType": "MicrosoftGraph"
        }
      ]
    }
  ]
}

Exemplo 5: Criar uma revisão de acesso num grupo com informações sobre a afiliação de utilizador para grupo e início de sessão do utilizador para obter recomendações

O exemplo seguinte cria uma revisão de acesso com as seguintes definições:

  • A revisão analisa todos os membros de um grupo com o ID02f3bafb-448c-487c-88c2-5fd65ce49a41.
  • Um utilizador específico com o ID398164b1-5196-49dd-ada2-364b49f99b27 de utilizador é o revisor.
  • Repete-se semanalmente e continua indefinidamente.
  • Tanto a afiliação de utilizador para grupo como o início de sessão de utilizador são informações para revisores.

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Test create",
    "descriptionForAdmins": "New scheduled access review",
    "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [
        {
            "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "instanceDurationInDays": 1,
        "recurrence": {
            "pattern": {
                "type": "weekly",
                "interval": 1
            },
            "range": {
                "type": "noEnd",
                "startDate": "2020-09-08T12:02:30.667Z"
            }
        },
        "recommendationInsightSettings": [
            {
                "@odata.type": "#microsoft.graph.userLastSignInRecommendationInsightSetting",
                "recommendationLookBackDuration": "P30D",
                "signInScope": "tenant"
            },
            {
                "@odata.type": "#microsoft.graph.groupPeerOutlierRecommendationInsightSettings"
            }
        ]
    }
}

Resposta

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

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

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Test create",
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers"
  },
  "reviewers": [
    {
      "query": "/users/7eae986b-d425-48b2-adf2-3c777f4444f3"
    }
  ],
  "settings": {
    "recommendationInsightSettings": [
      {
        "@odata.type": "#microsoft.graph.userLastSignInRecommendationInsightSetting",
        "recommendationLookBackDuration": "P30D",
        "signInScope": "tenant"
      },
      {
        "@odata.type": "#microsoft.graph.groupPeerOutlierRecommendationInsightSettings"
      }
    ]
  }
}