Поделиться через

Получение пользователя

  • Статья

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

Важно!

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

Получение свойств и связей объекта 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 дает приложению возможность читать профиль и обнаруживать отношения, такие как членство в группах, отчеты и руководитель пользователя, вошедшего в систему.
  • Чтобы прочитать свойство employeeLeaveDateTime, выполните следующие действия :
    • В делегированных сценариях администратору требуется по крайней мере одна из следующих ролей Microsoft Entra: администратор рабочих процессов жизненного цикла (минимальные привилегии), глобальный читатель; приложению должно быть предоставлено делегированное разрешение User-LifeCycleInfo.Read.All.
    • В сценариях только для приложений с разрешениями Microsoft Graph приложению должно быть предоставлено разрешение User-LifeCycleInfo.Read.All .
  • Чтобы прочитать свойство customSecurityAttributes , выполните следующие действия:
    • В делегированных сценариях администратору должна быть назначена роль администратора назначения атрибутов , а приложению — разрешение CustomSecAttributeAssignment.Read.All .
    • В сценариях только для приложений с разрешениями Microsoft Graph приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.Read.All .

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 для получения определенных свойств пользователя, включая те, которые не возвращаются по умолчанию. Свойства расширения также поддерживают параметры запроса следующим образом:

Тип расширения Комментарии
onPremisesExtensionAttributes 1-15 Возвращается только с помощью $select.
Расширения схемы Возвращается только с помощью $select.
Открытые расширения Возвращается только с помощью операции Получить открытое расширение.
Расширения каталога Возвращается только с помощью $select.

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

Заголовок Значение
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.

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

Не указывайте текст запроса для этого метода.

Отклик

При успешном выполнении этот метод возвращает код отклика 200 OK и объект user в тексте отклика. Он возвращает свойства по умолчанию, если не используется $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. Получение свойств указанного пользователя

Запрос

Ниже показан пример запроса.

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

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