Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Пространство имен: microsoft.graph
Важно!
API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Получение свойств и связей объекта пользователя . Если указанный идентификатор равен идентификатору agentUser, API возвращает свойства объекта agentUser .
Эта операция по умолчанию возвращает только подмножество наиболее часто используемых свойств. Эти свойства по умолчанию указаны в разделе Свойства. Чтобы получить свойства, которые не возвращаются по умолчанию, выполните операцию GET и укажите их в параметре запроса OData $select. Так как ресурс user поддерживает расширения, с помощью операции GET можно также получить настраиваемые свойства и данные расширения в экземпляре user.
Клиенты через Microsoft Entra ID для клиентов также могут использовать эту операцию API для получения сведений.
Этот API доступен в следующих национальных облачных развертываниях.
| Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Разрешения
Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.
| Тип разрешения | Разрешения с наименьшими привилегиями | Более высокие привилегированные разрешения |
|---|---|---|
| Делегированные (рабочая или учебная учетная запись) | User.Read | User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
| Делегированные (личная учетная запись Майкрософт) | User.Read | User.ReadWrite |
| Для приложений | User.Read.All | User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Примечание.
Разрешение User.Read позволяет приложению считывать профиль и обнаруживать такие связи, как членство в группе, отчеты и руководитель только вошедшего пользователя.
Разрешения для определенных сценариев
- Чтобы прочитать свойство employeeLeaveDateTime, выполните следующие действия :
- В делегированных сценариях вошедшему пользователю требуется по крайней мере одна из следующих Microsoft Entra ролей: администратор рабочих процессов жизненного цикла (минимальные привилегии), глобальный читатель; приложению должно быть предоставлено делегированное разрешение User-LifeCycleInfo.Read.All.
- В сценариях только для приложений с разрешениями Microsoft Graph приложению должно быть предоставлено разрешение User-LifeCycleInfo.Read.All .
- Чтобы прочитать свойство customSecurityAttributes , выполните следующие действия:
- В делегированных сценариях вошедшему пользователю должна быть назначена роль администратора назначения атрибутов , а приложению — разрешение CustomSecAttributeAssignment.Read.All .
- В сценариях только для приложений с разрешениями Microsoft Graph приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.Read.All .
- User-Mail.ReadWrite.All — это наименее привилегированное разрешение на чтение и запись свойства otherMails ; также позволяет считывать некоторые свойства, связанные с идентификатором, в объекте пользователя.
- User-PasswordProfile.ReadWrite.All — это наименее привилегированное разрешение на чтение и запись свойств, связанных со сбросом пароля; также позволяет считывать некоторые свойства, связанные с идентификатором, в объекте пользователя.
- User-Phone.ReadWrite.All — это наименее привилегированное разрешение на чтение и запись свойств businessPhones и mobilePhone ; также позволяет считывать некоторые свойства, связанные с идентификатором, в объекте пользователя.
- User.EnableDisableAccount.All + User.Read.All — это наименее привилегированное сочетание разрешений на чтение и запись свойства accountEnabled .
HTTP-запрос
Для вошедшего пользователя:
GET /me
Примечание.
Для вызова конечной точки /me требуется вход пользователя и, следовательно, делегированное разрешение. Разрешения приложений не поддерживаются при использовании конечной /me точки.
Для указанного пользователя или агентаПользователь:
GET /users/{id | userPrincipalName}
Совет
- Когда userPrincipalName начинается с символа
$, синтаксис URL-адреса запроса GET/users/$x@y.comприводит к сбою с кодом ошибки400 Bad Request. Запрос завершается ошибкой, так как URL-адрес нарушает соглашение о URL-адресе OData, которое предполагает, что только параметры системного запроса будут иметь префикс символа$. Удалите косую черту (/) после/usersи заключите userPrincipalName в скобки и одинарные кавычки следующим образом:/users('$x@y.com'). Например,/users('$AdeleVance@contoso.com'). - Чтобы запросить пользователя B2B с помощью userPrincipalName, закодируйте хэш-символ (#). То есть замените символ
#на%23. Например,/users/AdeleVance_adatum.com%23EXT%23@contoso.com.
Необязательные параметры запросов
Этот метод поддерживает $selectпараметр запроса OData для получения определенных свойств, включая свойства, которые не возвращаются по умолчанию. Свойства расширения также поддерживают параметры запроса следующим образом:
| Тип расширения | Комментарии |
|---|---|
| onPremisesExtensionAttributes 1-15 | Возвращается только с помощью $select. |
| Расширения схемы | Возвращается только с помощью $select. |
| Открытые расширения | Возвращается только с помощью операции Получить открытое расширение. |
| Расширения каталога | Возвращается только с помощью $select. |
Заголовки запросов
| Заголовок | Значение |
|---|---|
| Авторизация | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Текст запроса
Не указывайте текст запроса для этого метода.
Отклик
В случае успешного выполнения этот метод возвращает код отклика 200 OK и объект user или agentUser в тексте ответа. Он возвращает свойства по умолчанию, если не используется $select для указания конкретных свойств. В случае успешной обработки запроса этот метод возвращает 202 Accepted, но серверу требуется дополнительное время для выполнения соответствующих фоновых операций.
Если объект с идентификатором не существует, этот метод возвращает 404 Not Found код ошибки.
Пример
Пример 1. Получение свойств вошедшего пользователя или агента, прошедшего проверку подлинностиПользователь
Запрос
GET https://graph.microsoft.com/beta/me
Отклик
Ниже показан пример отклика. Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}
Пример 2. Получение свойств указанного пользователя
Запрос
Ниже показан пример запроса. Если указанный идентификатор равен идентификатору agentUser, API возвращает свойства объекта agentUser .
GET https://graph.microsoft.com/beta/users/{id}
Отклик
Ниже показан пример отклика.
HTTP/1.1 200 OK
Content-type: application/json
{
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}
Пример 3. Использование $select для получения определенных свойств пользователя
Чтобы получить определенные свойства, используйте параметр запроса $select OData. Например, чтобы вернуть displayName, givenName, postalCode и удостоверения, добавьте в запрос следующее выражение запроса. $select=displayName,givenName,postalCode,identities
Запрос
GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode,identities
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
"displayName": "Adele Vance",
"givenName": "Adele",
"postalCode": "98004",
"identities": [
{
"signInType": "userPrincipalName",
"issuer": "contoso.com",
"issuerAssignedId": "AdeleV@contoso.com"
}
]
}
Пример 4. Получение назначений настраиваемых атрибутов безопасности для пользователя
В следующем примере показано, как получить пользовательские назначения атрибутов безопасности для пользователя.
Атрибут №1
- Набор атрибутов:
Engineering - Атрибут:
Project - Тип данных атрибута: коллекция строк
- Значение атрибута:
["Baker","Cascade"]
Атрибут №2
- Набор атрибутов:
Engineering - Атрибут:
CostCenter - Тип данных атрибута: коллекция целых чисел
- Значение атрибута:
[1001]
Атрибут №3
- Набор атрибутов:
Engineering - Атрибут:
Certification - Тип данных атрибута: логический
- Значение атрибута:
true
Атрибут №4
- Набор атрибутов:
Marketing - Атрибут:
EmployeeId - Тип данных атрибута: строка
- Значение атрибута:
"QN26904"
Чтобы получить назначения настраиваемых атрибутов безопасности, вызывающему субъекту должна быть назначена роль читателя назначения атрибутов или администратора назначения атрибутов, а также должно быть предоставлено разрешение CustomSecAttributeAssignment.Read.All или CustomSecAttributeAssignment.ReadWrite.All.
Дополнительные примеры назначений настраиваемых атрибутов безопасности см. в разделе Примеры. Назначение, обновление, перечисление или удаление назначений настраиваемых атрибутов безопасности с помощью microsoft API Graph.
Запрос
GET https://graph.microsoft.com/beta/users/{id}?$select=customSecurityAttributes
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
"customSecurityAttributes": {
"Marketing": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"EmployeeId": "QN26904"
},
"Engineering": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Project@odata.type": "#Collection(String)",
"Project": [
"Baker",
"Cascade"
],
"CostCenter@odata.type": "#Collection(Int32)",
"CostCenter": [
1001
],
"Certification": true
}
}
}
Если пользователю не назначены настраиваемые атрибуты безопасности или у вызывающего субъекта нет доступа, ответ отображается в следующем блоке:
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}
Пример 5. Получение значения расширения схемы для пользователя.
В этом примере идентификатор расширения схемы — ext55gb1l09_msLearnCourses.
Запрос
GET https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
"ext55gb1l09_msLearnCourses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseType": "Developer",
"courseName": "Introduction to Microsoft Graph",
"courseId": 1
}
}