Работа с пользователями в Microsoft Graph

  • Статья

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

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

  • По идентификатору или userPrincipalName, /users/{id} или /users/{userPrincipalName}
  • С помощью псевдонима /me (который совпадает с /users/{signed-in user's id}) для пользователя, вошедшего в систему.

Общие операции API

Path Описание
/me Получение сведений о пользователе, выполнившего вход.
/users Вывод списка пользователей в организации.
/users/{id} Возвращает определенного пользователя по идентификатору.
/users/{id}/photo/$value Получение фотографии профиля пользователя.
/users/{id}/manager Получение сведений о руководителе пользователя.
/users/{id}/messages Вывод списка электронных писем пользователя в его основном почтовом ящике.
/users/{id}/events Вывод списка предстоящих событий пользователя из его календаря.
/users/{id}/drive Получение хранилища файлов OneDrive пользователя.
/users/{id}/memberOf Вывод списка групп, участником которых является пользователь.
/users/{id}/joinedTeams Вывод списка команд Microsoft Teams, участником которых является пользователь.

Авторизация и привилегии

Microsoft Graph поддерживает использование делегированных разрешений и разрешений приложений для управления операциями пользователей. Дополнительные сведения см. в разделе Делегированные разрешения и разрешения приложений и соответствующую справочную документацию по API для разрешений, необходимых для каждой операции.

Некоторые пользовательские операции могут выполняться вошедшего пользователя с использованием собственных сведений. Для таких операций пользователь может предоставить приложению разрешения Microsoft Graph на доступ к собственным сведениям. Разрешения User.ReadBasic.All, User.Read и User.ReadWrite являются такими разрешениями.

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

Разрешения пользователей по умолчанию в Microsoft Entra ID

В Microsoft Entra ID есть два типа пользователей : участники и гости. Изначально пользователи-члены создаются в клиенте. Гостевые пользователи присоединяются к клиенту путем активации своего приглашения и получают доступ к клиенту в качестве гостей совместной работы "бизнес-бизнес" (B2B).

Набор разрешений по умолчанию зависит от того, является ли пользователь участником или гостевым пользователем. Дополнительные сведения о том, что могут делать пользователи-члены и гостевые пользователи, см. в статье Какие разрешения пользователей по умолчанию в Microsoft Entra ID?.

Разрешения пользователей по умолчанию в клиентах клиентов

Существуют также разрешения по умолчанию для клиентов в Microsoft Entra ID для клиентов. В следующей таблице указаны операции API, позволяющие клиентам управлять своим профилем.

Идентификатор пользователя или userPrincipalName всегда является именем пользователя, выполнившего вход.

Операция пользователя Операция API Необходимые разрешения
Профиль чтения GET /me или GET /users/{id or userPrincipalName} User.Read
Обновление профиля PATCH /me или PATCH /users/{id or userPrincipalName}

Обновляемые свойства: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, surname и preferredLanguage		 User.ReadWrite
Смена пароля POST /me/changePassword Directory.AccessAsUser.All

Кто может сбрасывать пароли

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

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

Роль, которую можно сбросить пароль Пароль Администратор Администратор службы поддержки Проверка подлинности Администратор Администратор пользователя Привилегированная проверка подлинности Администратор Глобальный администратор
Проверка подлинности Администратор     ✅   ✅ ✅
Читатели каталогов ✅ ✅ ✅ ✅ ✅ ✅
Глобальный администратор         ✅ ✅*
Группы Администратор       ✅ ✅ ✅
Приглашающий гостей ✅ ✅ ✅ ✅ ✅ ✅
Администратор службы поддержки   ✅   ✅ ✅ ✅
Читатель центра сообщений   ✅ ✅ ✅ ✅ ✅
Пароль Администратор ✅ ✅ ✅ ✅ ✅ ✅
Привилегированная проверка подлинности Администратор         ✅ ✅
Администратор привилегированных ролей         ✅ ✅
Читатель отчетов   ✅ ✅ ✅ ✅ ✅
Пользователь
(без роли администратора)		 ✅ ✅ ✅ ✅ ✅ ✅
Пользователь
(нет роли администратора, но член или владелец группы с возможностью назначения ролей		         ✅ ✅
Пользователь с ролью, ограниченной административной единицей управления         ✅ ✅
Администратор пользователя       ✅ ✅ ✅
Средство чтения сводки об использовании   ✅ ✅ ✅ ✅ ✅
Все настраиваемые роли ✅ ✅

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

  • businessPhones
  • mobilePhone;
  • otherMails

Кто может выполнять конфиденциальные действия

Некоторые администраторы могут выполнять следующие конфиденциальные действия для некоторых пользователей. Все пользователи могут считывать конфиденциальные свойства.

Конфиденциальное действие Имя конфиденциального свойства
Отключение или включение пользователей accountEnabled
Обновление бизнес-телефона businessPhones
Обновление мобильного телефона mobilePhone;
Обновление локального неизменяемого идентификатора onPremisesImmutableId
Обновление других сообщений электронной почты otherMails
Обновление профиля пароля passwordProfile
Обновление имени участника-пользователя userPrincipalName.
Удаление или восстановление пользователей Неприменимо

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

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

Роль, с которой может выполняться конфиденциальное действие Проверка подлинности Администратор Администратор пользователя Привилегированная проверка подлинности Администратор Глобальный администратор
Проверка подлинности Администратор ✅   ✅ ✅
Читатели каталогов ✅ ✅ ✅ ✅
Глобальный администратор     ✅ ✅
Группы Администратор   ✅ ✅ ✅
Приглашающий гостей ✅ ✅ ✅ ✅
Администратор службы поддержки   ✅ ✅ ✅
Читатель центра сообщений ✅ ✅ ✅ ✅
Пароль Администратор ✅ ✅ ✅ ✅
Привилегированная проверка подлинности Администратор     ✅ ✅
Администратор привилегированных ролей     ✅ ✅
Читатель отчетов ✅ ✅ ✅ ✅
Пользователь
(без роли администратора)		 ✅ ✅ ✅ ✅
Пользователь
(нет роли администратора, но член или владелец группы с возможностью назначения ролей)		     ✅ ✅
Пользователь с ролью, ограниченной административной единицей управления     ✅ ✅
Администратор пользователя   ✅ ✅ ✅
Средство чтения сводки об использовании ✅ ✅ ✅ ✅
Все настраиваемые роли ✅ ✅

Общие свойства

Ниже показан набор свойств, используемый по умолчанию и возвращаемый при получении пользователя или выводе списка пользователей. Это подмножество всех доступных свойств. Чтобы получить дополнительные свойства пользователя, используйте параметр запроса $select. Узнайте, Как использовать параметр поискового запроса $select и каковы Свойства, поддерживающие параметр $select поискового запроса.

Свойство Описание
id Уникальный идентификатор для пользователя.
businessPhones Номера телефонов пользователя.
displayName Имя, отображаемое в адресной книге, для пользователя.
givenName Имя пользователя.
jobTitle Должность пользователя.
mail Электронный адрес пользователя.
mobilePhone Номер мобильного телефона пользователя.
officeLocation Физическое расположение офиса пользователя.
preferredLanguage Предпочитаемый язык пользователя.
surname Фамилия пользователя.
userPrincipalName Имя участника-пользователя для пользователя.

Дополнительные сведения и список всех свойств см. в статье об объекте user.

Ограничения на поиск пользователей и групп для гостевых пользователей в организациях

Функции поиска пользователей и групп позволяют приложению найти любого пользователя и любую группу в каталоге организации с помощью запросов для набора ресурсов /users или /groups (например, https://graph.microsoft.com/v1.0/users). Эту возможность имеют как администраторы, так и пользователи, являющиеся участниками; однако гостевые пользователи этого не сделали.

Если пользователь вошел как гость, в зависимости от предоставленных приложению разрешений оно может прочитать профиль определенного пользователя или определенной группы (например, https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531). Но оно не может отправлять набору ресурсов /users или /groups запросы, способные возвращать несколько ресурсов.

При наличии подходящих разрешений приложение может считывать профили пользователей и групп, которые оно получает благодаря ссылкам в свойствах навигации (например, /users/{id}/directReports или /groups/{id}/members).

Свойства, не возвращенные по умолчанию

Некоторые свойства объекта user не возвращаются по умолчанию и должны быть указаны в параметре $select запроса. Например, день рождения и навыки. См. таблицу свойств сущности пользователя , чтобы определить свойства, возвращаемые только в том случае, если вы $select.

Свойства, хранящиеся за пределами хранилища данных main

Хотя данные пользовательского ресурса в основном хранятся в Microsoft Entra ID, некоторые из его свойств, например навыки, хранятся в SharePoint Online. В большинстве случаев эти свойства нельзя указать в том же тексте запроса на создание или обновление, что и другие свойства пользователя.

Свойства, хранящиеся за пределами хранилища данных main, также не поддерживаются в рамках отслеживания изменений. Таким образом, изменение любого из этих свойств не приводит к отображению объекта в ответе разностного запроса.

Связанные материалы