unifiedRoleDefinition: atribuídoPrincipals

  • 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 entidades de segurança (usuários, grupos e entidades de serviço) atribuídas a uma função específica para diferentes escopos direta ou transitivamente. Você pode usar o $count parâmetro de consulta para também obter a contagem.

Para listar as atribuições de função direta e transitiva para uma entidade de segurança específica, use a API Lista transitiveRoleAssignments .

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

Se o chamador não tiver a permissão para ler propriedades de alguns dos objetos incluídos no conjunto de resultados, a resposta seguirá as informações limitadas retornadas para o padrão de objetos membro inacessíveis .

Para ler as propriedades que podem exigir permissões para o objeto, conceda as permissões para recuperar informações sobre o objeto. Para obter mais informações, consulte permissões para usuários, grupos e entidades de serviço.

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
Transitiva Booliano Indica se deve incluir entidades atribuídas por meio da associação de grupo (direta ou transitiva). false por padrão.
directoryScopeType Cadeia de caracteres O escopo do diretório para o qual as entidades são atribuídas. Os valores com suporte são tenant, administrativeUnite resource.
directoryScopeId Cadeia de caracteres ID do escopo do diretório para o qual as entidades são atribuídas. Por padrão, todos os escopos são considerados.

Você também pode combinar todos os parâmetros de função com suporte em uma solicitação para resultados refinados.

Exemplo de padrões de consulta para directoryScopeType

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

Parâmetros de consulta opcionais

Esse método dá suporte aos $countparâmetros de consulta , $select, $filtere $orderby OData para ajudar a personalizar a resposta. Você também pode filtrar pelo tipo de objeto usando a conversão 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 o uso de ConsistencyLevel, consulte Recursos avançados de consulta 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, essa função retornará um 200 OK código de resposta e uma coleção directoryObject no corpo da resposta.

Exemplos

Para os exemplos nesta seção, considere o cenário de atribuição de função a seguir. Um usuário chamado User1 tem atribuições de função diretas e transitivas da seguinte maneira:

Usuário Agrupar Role Escopo
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Role1 Escopo1
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Role1 Escopo2
Group1
86b38db7-6e8b-4ad2-b2aa-ced7f09486c1
(User1 é um membro)		 Role1 Escopo1
Group2
182351a6-d974-4d18-88ae-8a148da44cd2
(User1 é um membro)		 Role1 Escopo1
Group3
b93d5379-a464-4db5-b8e1-694910f1e11e
(User2 é um membro)
(User3 é um membro)		 Role1 Scope3
  • User1 recebe a função Role1 diretamente no escopo Scope1.
  • User1 recebe a função Role1 diretamente no escopo Scope2.
  • User1 é membro do grupo Group1 e Group1 recebe a função Role1 no escopo Scope1.
  • User1 é membro do grupo Group2 e Group2 recebe a função Role1 no escopo Scope1.
  • User2 é membro do grupo Group3 e o Group3 recebe a função Role1 no escopo Scope3.
  • User3 é membro do grupo Group3 e o Group3 recebe a função Role1 no escopo Scope3.

Exemplo 1: obter uma contagem de entidades de entidades atribuídas diretas e transitivas para todos os escopos

Solicitação

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

Resposta

A solicitação acima retorna uma contagem de 6 representando as seguintes atribuições de função:

  • Duas atribuições de função diretas para User1 em Scope1 e Scope2
  • Duas atribuições de função transitivas para User1 por group1 e Group2
  • Duas atribuições de função transitivas para Usuário 2 e User3 por meio do Group3.
HTTP/1.1 200 OK
Content-type: text/plain

6

Com base no mesmo cenário, os exemplos a seguir mostram as contagens retornadas para cada padrão de consulta:

Exemplo Contar
/assignedPrincipals(transitive=false)/$count 4
(User1, Group1, Group2, Group3)
/assignedPrincipals(transitive=false)/microsoft.graph.user/$count 1
(User1)
/assignedPrincipals(transitive=true)/microsoft.graph.user/$count 3
(User1, User2, User3)
/assignedPrincipals(transitive=false)/microsoft.graph.group/$count 3
(Group1, Group2, Group3)
/assignedPrincipals(transitive=true)/microsoft.graph.group/$count 3
(Group1, Group2, Group3)

Exemplo 2: obter entidades atribuídas diretamente para uma função de diretório e escopo 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 entidades diretamente atribuídas para todos os escopos

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 usuários atribuídos diretamente apenas para um escopo em todo o locatário

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 entidades diretamente atribuídas e contagem embutida

O exemplo a seguir obtém as entidades de segurança atribuídas diretamente e exibe uma contagem embutida.

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