Поделиться через

unifiedRoleDefinition: assignedPrincipals

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Получите список субъектов безопасности (пользователей, групп и субъектов-служб), которым назначена определенная роль для различных областей напрямую или транзитивно. Параметр запроса также можно использовать $count для получения счетчика.

Этот API поддерживается только для поставщика каталога (Microsoft Entra ID).

Чтобы получить список назначений прямых и транзитивных ролей для определенного субъекта, используйте API List transitiveRoleAssignments .

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Приложение RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory

Важно!

В делегированных сценариях с рабочими или учебными учетными записями вошедшему пользователю должна быть назначена поддерживаемая роль Microsoft Entra или настраиваемая роль с разрешением поддерживаемой роли. Для этой операции поддерживаются следующие наименее привилегированные роли:

  • Читатели каталогов
  • Глобальный читатель
  • Администратор привилегированных ролей

Важно!

Когда приложение запрашивает связь, которая возвращает коллекцию типов directoryObject , если у него нет разрешения на чтение определенного типа ресурсов, возвращаются члены этого типа, но с ограниченной информацией. Например, возвращается только свойство @odata.type для типа объекта и идентификатор , в то время как другие свойства указываются как null. При таком поведении приложения могут запрашивать необходимые разрешения с наименьшими привилегиями, а не полагаться на набор каталогов.*Разрешения. Сведения см. в разделе Ограниченные сведения, возвращаемые для недоступных объектов member.

HTTP-запрос

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

Параметры функции

В URL-адресе запроса укажите перечисленные ниже параметры запроса и их значения. В приведенной ниже таблице указаны параметры, которые можно использовать с этой функцией.

Параметр Тип Описание
переходный Логический Указывает, следует ли включать субъекты, назначенные через членство в группах (прямое или транзитивное). false по умолчанию.
directoryScopeType String Каталог область для получения назначенных субъектов. Поддерживаемые значения: tenant, administrativeUnitи resource.
directoryScopeId String Идентификатор каталога область для получения назначенных субъектов. По умолчанию учитываются все области.

Вы также можете объединить все поддерживаемые параметры функции в одном запросе для получения точных результатов.

Примеры шаблонов запросов для directoryScopeType

Scope Запрос Поддерживается для
Все области /assignedPrincipals(transitive={true | false}) Все роли
область клиента /assignedPrincipals(directoryScopeType='tenant', transitive={true | false}) Все роли
Все области административных единиц /assignedPrincipals(directoryScopeType='administrativeUnit', transitive={true | false}) Перечисление ролей каталога
Конкретная административная единица область /assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Перечисление ролей каталога
Все области ресурсов /assignedPrincipals(directoryScopeType='resource', transitive={true | false}) Перечисление ролей каталога
Конкретные область ресурсов /assignedPrincipals(directoryScopeType='resource', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Перечисление ролей каталога

Необязательные параметры запросов

Этот метод поддерживает $countпараметры запроса , $select, $filterи $orderby OData для настройки ответа. Вы также можете выполнять фильтрацию по типу объекта с помощью приведения OData. Например, /assignedPrincipals(transitive=false)/microsoft.graph.user и /assignedPrincipals(transitive=true)/microsoft.graph.servicePrincipal/$count. Общие сведения см. в статье Параметры запроса OData.

Заголовки запросов

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
ConsistencyLevel необязательный. Обязательно. Дополнительные сведения об использовании ConsistencyLevel см. в разделе Расширенные возможности запросов к объектам каталога.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

В случае успешного выполнения эта функция возвращает код отклика 200 OK и коллекцию directoryObject в теле отклика.

Примеры

Для примеров в этом разделе рассмотрим следующий сценарий назначения ролей. Пользователю с именем User1 назначены прямые и транзитивные роли, как показано ниже.

Пользователь Группа Роль Область
Пользователь_1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Role1 Scope1
Пользователь_1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Role1 Scope2
Group1
86b38db7-6e8b-4ad2-b2aa-ced7f09486c1
(Пользователь1 является участником)		 Role1 Scope1
Группа 2
182351a6-d974-4d18-88ae-8a148da44cd2
(Пользователь1 является участником)		 Role1 Scope1
Группа 3
b93d5379-a464-4db5-b8e1-694910f1e11e
(Пользователь2 является участником)
(Пользователь 3 является участником)		 Role1 Область 3
  • Пользователю 1 назначается роль Role1 непосредственно в область Scope1.
  • Пользователю 1 назначается роль Role1 непосредственно на область Scope2.
  • Пользователь User1 является членом группы Group1, а Group1 назначена роль Role1 на область Scope1.
  • Пользователь User1 входит в группу Group2, а группе 2 назначена роль Role1 на область Scope1.
  • Пользователь 2 является членом группы Group3, а группе 3 назначена роль Role1 в область Scope3.
  • Пользователь 3 является членом группы Group3, а группе 3 назначена роль Role1 в область Scope3.

Пример 1. Получение количества прямых и транзитивных назначенных субъектов для всех областей

Запрос

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

Отклик

Приведенный выше запрос возвращает число 6, представляющих следующие назначения ролей:

  • Два прямых назначения ролей пользователю User1 в Scope1 и Scope2
  • Два транзитивных назначения ролей для User1 по Group1 и Group2
  • Два транзитивных назначения ролей пользователю 2 и Пользователю 3 по Группе 3.
HTTP/1.1 200 OK
Content-type: text/plain

6

В соответствии с тем же сценарием в следующих примерах показаны счетчики, возвращаемые для каждого шаблона запроса:

Пример Count
/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)

Пример 2. Получение непосредственно назначенных субъектов для определенной административной единицы область и роли каталога

Запрос

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

Отклик

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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

Пример 3. Получение непосредственно назначенных субъектов для всех областей

Запрос

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

Отклик

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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

Пример 4. Получение непосредственно назначенных пользователей только для область на уровне клиента

Запрос

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

Отклик

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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

Пример 5. Получение непосредственно назначенных субъектов и встроенное число

В следующем примере получаются непосредственно назначенные субъекты и отображается встроенное число.

Запрос

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

Отклик

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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