Работа с пользователями в 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 |
Конфиденциальные действия
Следующие действия с объектом пользователя считаются конфиденциальными и могут быть заблокированы только определенными администраторами. Все пользователи могут считывать конфиденциальные свойства.
| Конфиденциальное действие | Имя конфиденциального свойства |
|---|---|
| Отключение или включение пользователей | accountEnabled |
| Обновление бизнес-телефона | businessPhones |
| Обновление мобильного телефона | mobilePhone; |
| Обновление локального неизменяемого идентификатора | onPremisesImmutableId |
| Обновление других сообщений электронной почты | otherMails |
| Обновление профиля пароля | passwordProfile |
| Обновление имени участника-пользователя | userPrincipalName. |
| Удаление или восстановление пользователей | Неприменимо |
Кто может выполнять конфиденциальные действия
Некоторые администраторы могут выполнять предыдущие конфиденциальные действия для некоторых пользователей.
В следующей таблице в столбцах перечислены роли, которые могут выполнять конфиденциальные действия. В строках перечислены роли, для которых может выполняться конфиденциальное действие.
В следующей таблице приведены роли, назначенные в область клиента. Для ролей, назначенных на область административной единицы, применяются дополнительные ограничения.
| Роль, с которой может выполняться конфиденциальное действие | Проверка подлинности Администратор | Администратор пользователя | Привилегированная проверка подлинности Администратор | Глобальный администратор |
|---|---|---|---|---|
| Проверка подлинности Администратор | ✅ | ✅ | ✅ | |
| Читатели каталогов | ✅ | ✅ | ✅ | ✅ |
| Глобальный администратор | ✅ | ✅ | ||
| Группы Администратор | ✅ | ✅ | ✅ | |
| Приглашающий гостей | ✅ | ✅ | ✅ | ✅ |
| Администратор службы поддержки | ✅ | ✅ | ✅ | |
| Читатель центра сообщений | ✅ | ✅ | ✅ | ✅ |
| Пароль Администратор | ✅ | ✅ | ✅ | ✅ |
| Привилегированная проверка подлинности Администратор | ✅ | ✅ | ||
| Администратор привилегированных ролей | ✅ | ✅ | ||
| Читатель отчетов | ✅ | ✅ | ✅ | ✅ |
| Пользователь (без роли администратора) |
✅ | ✅ | ✅ | ✅ |
| Пользователь (нет роли администратора, но член или владелец группы с возможностью назначения ролей) |
✅ | ✅ | ||
| Пользователь с ролью, ограниченной административной единицей управления | ✅ | ✅ | ||
| Администратор пользователя | ✅ | ✅ | ✅ | |
| Средство чтения сводки об использовании | ✅ | ✅ | ✅ | ✅ |
| Все настраиваемые роли | ✅ | ✅ |
Кто может сбрасывать пароли
В следующей таблице в столбцах перечислены роли, которые могут сбрасывать пароли и отменять маркеры обновления. В строках перечислены роли, для которых можно сбросить пароль. Например, администратор паролей может сбросить пароль для читателей каталогов, приглашенного гостя, администратора паролей и пользователей без роли администратора. Если пользователю назначена какая-либо другая роль, администратор паролей не может сбросить пароль.
В следующей таблице приведены роли, назначенные в область клиента. Для ролей, назначенных на область административной единицы, применяются дополнительные ограничения.
| Роль, которую можно сбросить пароль | Пароль Администратор | Администратор службы поддержки | Проверка подлинности Администратор | Администратор пользователя | Привилегированная проверка подлинности Администратор | Глобальный администратор |
|---|---|---|---|---|---|---|
| Проверка подлинности Администратор | ✅ | ✅ | ✅ | |||
| Читатели каталогов | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Глобальный администратор | ✅ | ✅* | ||||
| Группы Администратор | ✅ | ✅ | ✅ | |||
| Приглашающий гостей | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Администратор службы поддержки | ✅ | ✅ | ✅ | ✅ | ||
| Читатель центра сообщений | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Пароль Администратор | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Привилегированная проверка подлинности Администратор | ✅ | ✅ | ||||
| Администратор привилегированных ролей | ✅ | ✅ | ||||
| Читатель отчетов | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Пользователь (без роли администратора) |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Пользователь (нет роли администратора, но член или владелец группы с возможностью назначения ролей) |
✅ | ✅ | ||||
| Пользователь с ролью, ограниченной административной единицей управления | ✅ | ✅ | ||||
| Администратор пользователя | ✅ | ✅ | ✅ | |||
| Средство чтения сводки об использовании | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Все настраиваемые роли | ✅ | ✅ |
Возможность сброса пароля включает в себя возможность обновления следующих конфиденциальных свойств, необходимых для самостоятельного сброса пароля:
- businessPhones
- mobilePhone;
- otherMails
Общие свойства
Ниже показан набор свойств, используемый по умолчанию и возвращаемый при получении пользователя или выводе списка пользователей. Это подмножество всех доступных свойств. Чтобы получить дополнительные свойства пользователя, используйте параметр запроса $select. Узнайте, Как использовать параметр поискового запроса $select и каковы Свойства, поддерживающие параметр $select поискового запроса.
| Свойство | Описание |
|---|---|
| id | Уникальный идентификатор для пользователя. |
| businessPhones | Номера телефонов пользователя. |
| displayName | Имя, отображаемое в адресной книге, для пользователя. |
| givenName | Имя пользователя. |
| jobTitle | Должность пользователя. |
| Электронный адрес пользователя. | |
| 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, также не поддерживаются в рамках отслеживания изменений. Таким образом, изменение любого из этих свойств не приводит к отображению объекта в ответе разностного запроса.