Получение пользователя
Пространство имен: microsoft.graph
Получение свойств и связей объекта user.
Эта операция по умолчанию возвращает для каждого пользователя только подмножество наиболее часто используемых свойств. Эти свойства по умолчанию указаны в разделе Свойства. Чтобы получить свойства, которые не возвращаются по умолчанию, выполните операцию GET и укажите их в параметре $select
запроса OData. Так как ресурс 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 |
Совет
- Для вызова конечной точки
/me
требуется вход пользователя и, следовательно, делегированное разрешение. Разрешения приложений не поддерживаются при использовании конечной точки/me
. - Разрешение
User.Read
дает приложению возможность читать профиль и обнаруживать отношения, такие как членство в группах, отчеты и руководитель пользователя, вошедшего в систему.
HTTP-запрос
Для определенного пользователя:
GET /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
.
Для вошедшего пользователя:
GET /me
Необязательные параметры запроса
Этот метод поддерживает $select
параметр запроса OData для получения определенных свойств пользователя, включая те, которые не возвращаются по умолчанию.
По умолчанию возвращается только ограниченный набор свойств (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName).
Чтобы возвратить альтернативный набор свойств, необходимо указать нужный набор свойств user с помощью параметра запроса OData $select
. Например, чтобы вернуть displayName, givenName и postalCode, добавьте в запрос $select=displayName,givenName,postalCode
следующее выражение .
Свойства расширения также поддерживают параметры запроса следующим образом:
Тип расширения | Комментарии |
---|---|
onPremisesExtensionAttributes 1-15 | Возвращается только с помощью $select . |
Расширения схемы | Возвращается только с помощью $select . |
Открытые расширения | Возвращается только с помощью операции Получить открытое расширение. |
Расширения каталога | Возвращается только с помощью $select . |
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Текст запроса
Не указывайте текст запроса для этого метода.
Отклик
При успешном выполнении этот метод возвращает код отклика 200 OK
и объект user в тексте отклика. Он возвращает свойства по умолчанию, если не используется $select
для указания конкретных свойств.
В случае успешной обработки запроса этот метод возвращает 202 Accepted
, но серверу требуется дополнительное время для выполнения соответствующих фоновых операций.
Примеры
Пример 1. Обычный запрос пользователей
Запрос
По умолчанию возвращается только ограниченный набор свойств (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName). В этом примере показаны запрос и ответ по умолчанию.
GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"businessPhones": [
"+1 425 555 0109"
],
"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. Запрос для вошедшего пользователя
Вы можете получить информацию о вошедшем пользователе, заменив /users/{id | userPrincipalName}
на /me
.
Запрос
GET https://graph.microsoft.com/v1.0/me
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"businessPhones": [
"+1 425 555 0109"
],
"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/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$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. Получение значения расширения схемы для пользователя
Идентификатор расширения схемы в этом примере: ext55gb1l09_msLearnCourses
Запрос
GET https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
"ext55gb1l09_msLearnCourses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseType": "Developer",
"courseName": "Introduction to Microsoft Graph",
"courseId": 1
}
}
Пример 5. Получение назначений настраиваемых атрибутов безопасности для пользователя
В следующем примере показано, как получить пользовательские назначения атрибутов безопасности для пользователя.
Атрибут №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/v1.0/users/{id}?$select=customSecurityAttributes
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$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/v1.0/$metadata#users(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по