Partilhar via

unifiedRoleDefinition: assignedPrincipals

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

Obtenha a lista de principais de segurança (utilizadores, grupos e principais de serviço) atribuídos a uma função específica para diferentes âmbitos, direta ou transitivamente. Pode utilizar o $count parâmetro de consulta para obter também a contagem.

Esta API é suportada apenas para o fornecedor de diretórios (Microsoft Entra ID).

Para listar as atribuições de funções diretas e transitivas de um principal específico, utilize a API TransitiveRoleAssignments da Lista .

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) RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory

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:

  • Leitores de Diretórios
  • Leitor Global
  • Administrador de Função Privilegiada

Importante

Quando uma aplicação consulta uma relação que devolve uma coleção de tipo directoryObject , se não tiver permissão para ler um determinado tipo de recurso, os membros desse tipo são devolvidos, mas com informações limitadas. Por exemplo, apenas a propriedade @odata.type para o tipo de objeto e o ID é devolvido, enquanto outras propriedades são indicadas como null. Com este comportamento, as aplicações podem pedir as permissões menos privilegiadas de que precisam, em vez de dependerem do conjunto de Diretórios.* permissões. Para obter mais detalhes, confira Informações limitadas retornadas para objetos membro inacessíveis.

Solicitação HTTP

GET /roleManagement/directory/roleDefinitions/{unifiedRoleDefinitionId}/assignedPrincipals(transitive=@transitive,directoryScopeType='@directoryScopeType',directoryScopeId='@directoryScopeId')

Parâmetros de função

Na URL da solicitação, forneça os seguintes parâmetros de consulta com valores. A tabela a seguir mostra os parâmetros que podem ser usados com esta função.

Parâmetro Tipo Descrição
transitivo Booliano Indica se deve incluir principais atribuídos através da associação a grupos (direto ou transitivo). false por predefinição.
directoryScopeType Cadeia de caracteres O âmbito do diretório para o que são atribuídos principais. Os valores suportados são tenant, administrativeUnite resource.
directoryScopeId Cadeia de caracteres ID do âmbito do diretório para o que foram atribuídos principais. Por predefinição, todos os âmbitos são considerados.

Também pode combinar todos os parâmetros de função suportados num pedido de resultados detalhados.

Padrões de consulta de exemplo para directoryScopeType

Escopo Consultar Suportado para
Todos os âmbitos /assignedPrincipals(transitive={true | false}) Todas as funções
Âmbito do inquilino /assignedPrincipals(directoryScopeType='tenant', transitive={true | false}) Todas as funções
Todos os âmbitos de unidade administrativa /assignedPrincipals(directoryScopeType='administrativeUnit', transitive={true | false}) Funções de diretório
Âmbito de unidade administrativa específico /assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Funções de diretório
Todos os âmbitos de recursos /assignedPrincipals(directoryScopeType='resource', transitive={true | false}) Funções de diretório
Âmbito de recurso específico /assignedPrincipals(directoryScopeType='resource', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Funções de diretório

Parâmetros de consulta opcionais

Este método suporta os $countparâmetros de consulta , $select, $filtere $orderby OData para ajudar a personalizar a resposta. Também pode filtrar pelo tipo de objeto com a conversão de OData. Por exemplo, /assignedPrincipals(transitive=false)/microsoft.graph.user e /assignedPrincipals(transitive=true)/microsoft.graph.servicePrincipal/$count. Para obter informações gerais, acesse Parâmetros de consulta OData.

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
ConsistencyLevel eventualmente. Obrigatório. Para obter mais informações sobre a utilização de ConsistencyLevel, veja Advanced query capabilities on directory objects (Capacidades de consulta avançadas em objetos de diretório).

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se for bem-sucedida, esta função devolve um 200 OK código de resposta e uma coleção directoryObject no corpo da resposta.

Exemplos

Para os exemplos nesta secção, considere o seguinte cenário de atribuição de função. Um utilizador com o nome User1 tem atribuições de funções diretas e transitivas da seguinte forma:

Usuário Group Role Escopo
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Função1 Âmbito1
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Função1 Âmbito2
Grupo1
86b38db7-6e8b-4ad2-b2aa-ced7f09486c1
(O Utilizador1 é membro)		 Função1 Âmbito1
Grupo2
182351a6-d974-4d18-88ae-8a148da44cd2
(O Utilizador1 é membro)		 Função1 Âmbito1
Grupo3
b93d5379-a464-4db5-b8e1-694910f1e11e
(O Utilizador2 é membro)
(O Utilizador3 é membro)		 Função1 Âmbito3
  • É atribuída ao Utilizador1 a função Role1 diretamente no âmbito Scope1.
  • É atribuída ao Utilizador1 a função Role1 diretamente no âmbito Scope2.
  • O Utilizador1 é membro do grupo Grupo1 e é atribuída a função Role1 no âmbito Scope1.
  • O Utilizador1 é membro do grupo Grupo2 e é atribuída a função Role1 no âmbito Scope1.
  • O Utilizador2 é membro do grupo Grupo3 e o Grupo3 tem a função Role1 atribuída no âmbito Âmbito3.
  • O Utilizador3 é membro do grupo Grupo3 e é atribuída a função Role1 no âmbito Scope3.

Exemplo 1: Obter uma contagem de principais atribuídos diretos e transitivos para todos os âmbitos

Solicitação

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(transitive=true)/$count

Resposta

O pedido acima devolve uma contagem de 6 que representa as seguintes atribuições de funções:

  • Duas atribuições de funções diretas para o Utilizador1 no Âmbito1 e No Âmbito2
  • Duas atribuições de funções transitivas para Utilizador1 a Grupo1 e Grupo2
  • Duas atribuições de funções transitivas para o Utilizador 2 e o Utilizador3 até ao Grupo3.
HTTP/1.1 200 OK
Content-type: text/plain

6

Com base no mesmo cenário, os exemplos seguintes mostram as contagens que são devolvidas para cada padrão de consulta:

Exemplo Contar
/assignedPrincipals(transitive=false)/$count 4
(Utilizador1, Grupo1, Grupo2, Grupo3)
/assignedPrincipals(transitive=false)/microsoft.graph.user/$count 1
(Utilizador1)
/assignedPrincipals(transitive=true)/microsoft.graph.user/$count 3
(Utilizador1, Utilizador2, Utilizador3)
/assignedPrincipals(transitive=false)/microsoft.graph.group/$count 3
(Grupo1, Grupo2, Grupo3)
/assignedPrincipals(transitive=true)/microsoft.graph.group/$count 3
(Grupo1, Grupo2, Grupo3)

Exemplo 2: Obter principais atribuídos diretamente para uma função de diretório e âmbito de unidade administrativa específica

Solicitação

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='d0c2e067-9ae9-4dbf-a280-51a51c46f432')

Resposta

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f"
    }
  ]
}

Exemplo 3: Obter principais atribuídos diretamente para todos os âmbitos

Solicitação

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals

Resposta

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}

Exemplo 4: Obter utilizadores atribuídos diretamente apenas para um âmbito ao nível do inquilino

Solicitação

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='tenant')/microsoft.graph.user

Resposta

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users",
  "value": [
    {
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    }
  ]
}

Exemplo 5: Obter principais atribuídos diretamente e contagem inline

O exemplo seguinte obtém os principais atribuídos diretamente e apresenta uma contagem inline.

Solicitação

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals?$count=true

Resposta

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "@odata.count": 4,
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}