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

Перечисление пользователей

  • Статья

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

Важно!

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

Получение списка объектов user.

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

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

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

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Для приложений User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Гостевые пользователи не могут вызывать этот API. Дополнительные сведения о разрешениях для участников и гостевых пользователей см. в статье Какие разрешения пользователей по умолчанию используются в Microsoft Entra ID?.

Разрешения для определенных сценариев

  • User-Mail.ReadWrite.All — это наименее привилегированное разрешение на чтение и запись свойства otherMails ; также позволяет считывать некоторые свойства, связанные с идентификатором, в объекте пользователя.
  • User-PasswordProfile.ReadWrite.All — это наименее привилегированное разрешение на чтение и запись свойств, связанных со сбросом пароля; также позволяет считывать некоторые свойства, связанные с идентификатором, в объекте пользователя.
  • User-Phone.ReadWrite.All — это наименее привилегированное разрешение на чтение и запись свойств businessPhones и mobilePhone ; также позволяет считывать некоторые свойства, связанные с идентификатором, в объекте пользователя.
  • User.EnableDisableAccount.All + User.Read.All — это наименее привилегированное сочетание разрешений на чтение и запись свойства accountEnabled .

HTTP-запрос

GET /users

Необязательные параметры запросов

Этот метод поддерживает $countпараметры запроса OData , $expand$filter, $orderby, $search, $select, и $top для настройки ответа. $skip не поддерживается. По умолчанию и максимальный размер страницы — 100 и 999 объектов пользователя соответственно, за исключением случаев, когда вы указываете $select=signInActivity или $filter=signInActivity. Если signInActivity выбран или отфильтрован, максимальный размер страницы составляет 999. Некоторые запросы поддерживаются только при использовании заголовка ConsistencyLevel с присвоенным значением eventual и $count. Дополнительные сведения см. в разделе Расширенные возможности запросов к объектам каталогов. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

Свойства расширения также поддерживают параметры запроса, в некоторых случаях только с расширенными параметрами запроса. Дополнительные сведения см. в разделе Поддержка $filter свойств расширения.

Определенные свойства не могут быть возвращены в коллекции пользователей. Следующие свойства поддерживаются только при получении одного пользователя: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, обязанности, учебные заведения, навыки, mailboxSettings.

Следующие свойства не поддерживаются в личных учетных записях Майкрософт и будут null: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.

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

Заголовок Значение
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
ConsistencyLevel необязательный. Этот заголовок и $count требуются при использовании $search или определенном использовании $filter. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

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

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

Отклик

При успешном выполнении этот метод возвращает код ответа 200 OK и коллекцию объектов user в теле ответа.

Попытка использовать $select в коллекции /users для извлечения свойств, которые невозможно возвратить в пользовательской коллекции (например, запрос../users?$select=aboutMe), возвращает код ошибки 501 Not Implemented.

Примеры

Пример 1. Получение всех пользователей

Запрос

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

GET https://graph.microsoft.com/beta/users

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value":[
    {
      "displayName":"contoso1",
      "mail":"'contoso1@gmail.com",
      "mailNickname":"contoso1_gmail.com#EXT#",
      "otherMails":["contoso1@gmail.com"],
      "proxyAddresses":["SMTP:contoso1@gmail.com"],
      "userPrincipalName":"contoso1_gmail.com#EXT#@contoso.com"
    }
  ]
}

Пример 2. Получение учетной записи пользователя с помощью имени для входа

Найдите учетную запись пользователя, используя имя для входа (также называемое локальной учетной записью).

Примечание. При фильтрации по свойству issuerAssignedId требуется указывать параметры issuer и issuerAssignedId. Однако в некоторых сценариях значение issuer будет игнорироваться. Дополнительные сведения о фильтрации удостоверений см. в типе ресурса objectIdentity.

Запрос

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

GET https://graph.microsoft.com/beta/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

Пример 3. Получение гостевых пользователей (B2B) из определенного клиента или домена по userPrincipalName

Запрос

Ниже показан пример запроса. Значение userPrincipalName для гостевых пользователей (совместная работа B2B) всегда содержит идентификатор "#EXT#". Например, userPrincipalName пользователя в домашнем клиенте имеет значение AdeleV@adatum.com. При приглашении пользователя для совместной работы в клиенте contoso.com его userPrincipalName в клиенте будет "AdeleV_adatum.com#EXT#@contoso.com".

Для этого запроса необходимо задать для заголовка ConsistencyLevel значение eventual и $count=true строку запроса, так как запрос включает оператор endsWith. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

ЗАМЕТКА: Зарезервированный символ "#" в значении userPrincipalName необходимо закодировать как "%23" в URL-адресе запроса. Дополнительные сведения см. в разделе Кодировка специальных символов.

GET https://graph.microsoft.com/beta/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
ConsistencyLevel: eventual

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

Пример 4. Список времени последнего входа пользователей с определенным отображаемым именем

Запрос

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

Примечание.

Для сведений о свойстве signInActivity требуется лицензия Microsoft Entra ID P1 или P2 и AuditLog.Read.All разрешение.

GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity",
  "value": [
    {
      "displayName": "Eric Solomon",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    }
  ]
}

Пример 5: перечисление времени последнего входа пользователей в определенный временной диапазон

Запрос

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

Примечание.

Для сведений о свойстве signInActivity требуется лицензия Microsoft Entra ID P1 или P2 и AuditLog.Read.All разрешение.

GET https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": "",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    }
  ]
}

Пример 6. Получение только количества пользователей

Запрос

Ниже показан пример запроса. Для этого запроса требуется заголовок ConsistencyLevel с присвоенным значением eventual, так как в запросе присутствует $count. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

Примечание. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

GET https://graph.microsoft.com/beta/users/$count
ConsistencyLevel: eventual

Отклик

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

HTTP/1.1 200 OK
Content-type: text/plain

893

Пример 7. Использование параметров $filter и $top для получения одного пользователя с отображаемым именем, которое начинается с "а", включая количество возвращаемых объектов

Запрос

Ниже показан пример запроса. Для этого запроса требуется заголовок ConsistencyLevel с присвоенным значением eventual и строка запроса $count=true, так как запрос содержит параметры запроса $orderby и $filter. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

Примечание. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "otherMails":["a@contoso.com"],
      "proxyAddresses":["SMTP:a@contoso.com"],
      "userPrincipalName":"a_contoso.com#EXT#@contoso.com"
    }
  ]
}

Пример 8. Использование $filter для получения всем пользователям сообщения, заканчивающегося на "a@contoso.com", включая количество возвращаемых объектов, с результатами, упорядоченными по userPrincipalName

Запрос

Ниже показан пример запроса. Для этого запроса требуется заголовок ConsistencyLevel с присвоенным значением eventual и строка запроса $count=true, так как запрос содержит параметры запроса $orderby и $filter, а также использует оператор endsWith. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

Примечание. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

GET https://graph.microsoft.com/beta/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

Пример 9. Использование параметра $search для получения пользователей с отображаемыми именами, содержащими буквы "wa", включая количество возвращаемых объектов

Запрос

Ниже показан пример запроса. Для этого запроса требуется заголовок ConsistencyLevel с присвоенным значением eventual, так как в запросе присутствует $search. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

Примечание. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

GET https://graph.microsoft.com/beta/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Пример 10. Использование параметра $search для получения пользователей с отображаемыми именами, содержащими буквы "wa" или буквы "ad", включая количество возвращаемых объектов

Запрос

Ниже показан пример запроса. Для этого запроса требуется заголовок ConsistencyLevel с присвоенным значением eventual, так как в запросе присутствует $search. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

Примечание. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

GET https://graph.microsoft.com/beta/users?$search="displayName:wa" OR "displayName:ad"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

Отклик

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "mail":"'contosoadmin1@gmail.com",
      "mailNickname":"contosoadmin1_gmail.com#EXT#",
      "proxyAddresses":["SMTP:contosoadmin1@gmail.com"],
      "userPrincipalName":"contosoadmin1_gmail.com#EXT#@contoso.com"
    }
  ]
}

Пример 11. Использование $filter для получения пользователей, которым назначена определенная лицензия

Запрос

Ниже показан пример запроса. Для этого запроса требуется заголовок ConsistencyLevel с присвоенным значением eventual, так как в запросе присутствует $search. Дополнительные сведения об использовании ConsistencyLevel и $countсм. в разделе Дополнительные возможности запросов к объектам каталога.

Примечание. В настоящее время параметры $count и $search недоступны в клиентах Azure AD B2C.

GET https://graph.microsoft.com/beta/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

Отклик

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

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}

Пример 12. Получение значения расширения схемы для всех пользователей.

В этом примере идентификатор расширения схемы — ext55gb1l09_msLearnCourses.

Запрос

GET https://graph.microsoft.com/beta/users?$select=ext55gb1l09_msLearnCourses

Отклик

В следующем отклике свойство расширения ext55gb1l09_msLearnCourses схемы не назначено в двух объектах пользователя.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(ext55gb1l09_msLearnCourses)",
    "value": [
        {},
        {
            "ext55gb1l09_msLearnCourses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Developer",
                "courseName": "Introduction to Microsoft Graph",
                "courseId": 1
            }
        },
        {}
    ]
}

Примечание. Также можно применить $filter к свойству расширения схемы, чтобы получить объекты, в которых свойство в коллекции соответствует указанному значению. Используется следующий синтаксис: /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. Например, GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. Поддерживаемые операторы: eq и not.

Пример 13. Перечисление всех пользователей с пользовательским назначением атрибута безопасности, равным значению

В следующем примере показано, как вывести список всех пользователей с пользовательским назначением атрибута безопасности, равным значению. В этом примере извлекаются пользователи с настраиваемым атрибутом AppCountry безопасности со значением , равным Canada. Значение фильтра учитывает регистр. Необходимо добавить ConsistencyLevel=eventual в запрос или заголовок. Необходимо также включить, $count=true чтобы убедиться, что запрос маршрутизируется правильно.

Пользователь No 1

  • Набор атрибутов: Marketing
  • Атрибут: AppCountry
  • Тип данных атрибута: коллекция строк
  • Значение атрибута: ["India","Canada"]

Пользователь No 2

  • Набор атрибутов: Marketing
  • Атрибут: AppCountry
  • Тип данных атрибута: коллекция строк
  • Значение атрибута: ["Canada","Mexico"]

Чтобы получить назначения настраиваемых атрибутов безопасности, вызывающему субъекту должна быть назначена роль читателя назначения атрибутов или администратора назначения атрибутов, а также должно быть предоставлено разрешение CustomSecAttributeAssignment.Read.All или CustomSecAttributeAssignment.ReadWrite.All.

Примеры назначений настраиваемых атрибутов безопасности см. в разделе Примеры. Назначение, обновление, перечисление или удаление назначений настраиваемых атрибутов безопасности с помощью API Graph Майкрософт.

Запрос

GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
ConsistencyLevel: eventual

Отклик

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 2,
    "value": [
        {
            "id": "dbaf3778-4f81-4ea0-ac1c-502a293c12ac",
            "displayName": "Jiya",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Datacenter@odata.type": "#Collection(String)",
                    "Datacenter": [
                        "India"
                    ]
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "India",
                        "Canada"
                    ],
                    "EmployeeId": "KX19476"
                }
            }
        },
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Пример 14. Перечисление всех пользователей, управление которыми ограничено

Запрос

GET https://graph.microsoft.com/beta/users?$filter=isManagementRestricted eq true&$select=displayName,userPrincipalName

Отклик

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName,userPrincipalName)",
    "value": [
        {
            "displayName": "Adele",
            "userPrincipalName": "Adele@contoso.com"
        },
        {
            "displayName": "Bob",
            "userPrincipalName": "Bob@contoso.com"
        }
    ]
}