unifiedRoleDefinition: assignedPrincipals

Статья
02/14/2024

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

Важно!

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

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

Чтобы получить список назначений прямых и транзитивных ролей для определенного субъекта, используйте 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

Если вызывающий объект не имеет разрешения на чтение свойств для некоторых объектов, включенных в результирующий набор, ответ будет соответствовать ограниченной информации, возвращаемой шаблону недоступных объектов-членов .

Чтобы прочитать свойства, которым могут потребоваться разрешения для объекта, предоставьте разрешения на получение сведений об объекте. Дополнительные сведения см. в разделе Разрешения для пользователей, групп и субъектов-служб.

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')


const options = {
	authProvider,
};

const client = Client.init(options);

let assignedPrincipals = await client.api('/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='d0c2e067-9ae9-4dbf-a280-51a51c46f432')')
	.version('beta')
	.get();

Важно!

Пакеты SDK для Microsoft Graph по умолчанию используют версию API версии 1.0 и поддерживают не все типы, свойства и API, доступные в бета-версии. Дополнительные сведения о доступе к бета-API с помощью SDK см. в статье Использование пакетов Microsoft Graph SDK с бета-API.

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

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. Получение непосредственно назначенных субъектов для всех областей

Запрос

HTTP
JavaScript

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


const options = {
	authProvider,
};

const client = Client.init(options);

let assignedPrincipals = await client.api('/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals')
	.version('beta')
	.get();

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

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. Получение непосредственно назначенных пользователей только для область на уровне клиента

Запрос

HTTP
JavaScript

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


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='tenant')/microsoft.graph.user')
	.version('beta')
	.get();

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

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. Получение непосредственно назначенных субъектов и встроенное число

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

Запрос

HTTP
JavaScript

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


const options = {
	authProvider,
};

const client = Client.init(options);

let assignedPrincipals = await client.api('/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals')
	.version('beta')
	.get();

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

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

unifiedRoleDefinition: assignedPrincipals

Разрешения

HTTP-запрос

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

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

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

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

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

Отклик

Примеры

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

Запрос

Отклик

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

Запрос

Отклик

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

Запрос

Отклик

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

Запрос

Отклик

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

Запрос

Отклик

Обратная связь

Обратная связь

Дополнительные ресурсы