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


Перечисление участников группы

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

Получение списка непосредственных участников группы. Участниками группы могут быть пользователи, контакты организации, устройства, субъекты-службы и другие группы. Эта операция не является транзитивной.

Важно!

Этот API имеет известную проблему, из-за которой субъекты-службы не указаны в качестве членов группы в версии 1.0. В качестве обходного решения используйте этот API в конечной точке beta/groups/{id}?$expand=members или используйте API. Дополнительные сведения см. в статье Об известной проблеме.

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

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

Разрешения

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

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

Важно!

Когда приложение запрашивает связь, которая возвращает коллекцию типов directoryObject , если у него нет разрешения на чтение определенного типа ресурсов, возвращаются члены этого типа, но с ограниченной информацией. Например, возвращается только свойство @odata.type для типа объекта и идентификатор , в то время как другие свойства указываются как null. При таком поведении приложения могут запрашивать необходимые разрешения с наименьшими привилегиями, а не полагаться на набор каталогов.*Разрешения. Сведения см. в разделе Ограниченные сведения, возвращаемые для недоступных объектов member.

В делегированных сценариях пользователю, выполнившему вход, также необходимо назначить поддерживаемую роль Microsoft Entra или пользовательскую роль с разрешением microsoft.directory/groups/members/read роли или microsoft.directory/groups/members/limitedRead ролью для microsoft.directory/groups/hiddenMembers/read чтения скрытых членов. Для этой операции поддерживаются следующие наименее привилегированные роли:

  • Владельцы групп
  • Пользователи -члены
  • "Гостевые" пользователи — имеют ограниченные разрешения на чтение
  • Читатели каталогов
  • Запись каталогов
  • Администратор Группы
  • Администратор пользователей — включение скрытых участников
  • Администратор Exchange — включение скрытых участников
  • Администратор SharePoint — включение скрытых участников
  • администратор Intune — включение скрытых участников
  • Администратор Teams — включение скрытых участников
  • Администратор Yammer — включение скрытых участников

Для вывода списка участников скрытой группы членства также требуется разрешение Member.Read.Hidden .

HTTP-запрос

GET /groups/{id}/members

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

Этот метод поддерживает $filterпараметры запроса OData , $count$select, $search, $top, $search, и $expand для настройки ответа. Стандартный и максимальный размеры страницы — 100 и 999 объектов групп соответственно. Некоторые запросы поддерживаются только при использовании заголовка ConsistencyLevel с присвоенным значением eventual и $count. Дополнительные сведения см. в разделе Расширенные возможности запросов к объектам каталогов.

Приведение OData также включено. Например, /groups/{id}}/members/microsoft.graph.user извлекает участников группы, которые являются пользователями.

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

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

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

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

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и коллекцию объектов directoryObject в тексте отклика.

Попытка фильтрации по приведения OData, представляющего неподдерживаемый тип элемента, возвращает ошибку 400 Bad RequestRequest_UnsupportedQuery с кодом. Например, /groups/{id}}/members/microsoft.graph.group если группа является группой Microsoft 365, она вернет эту ошибку, так как группы Microsoft 365 не могут иметь другие группы в качестве участников.

Примеры

Пример 1. Получение сведений о непосредственном участии в группе

Запрос

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

GET https://graph.microsoft.com/v1.0/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members

Отклик

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
  "value": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "mail": "user1@contoso.com"
    }
  ]
}

Пример 2. Получение только количества всех участий

Запрос

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

GET https://graph.microsoft.com/v1.0/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/$count
ConsistencyLevel: eventual

Отклик

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

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

893

Пример 3. Использование приведения к OData для получения только количества участий пользователей

Запрос

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

GET https://graph.microsoft.com/v1.0/groups/{id}/members/microsoft.graph.user/$count
ConsistencyLevel: eventual

Отклик

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

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

893

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

Запрос

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

GET https://graph.microsoft.com/v1.0/groups/{id}/members/microsoft.graph.user?$count=true&$orderby=displayName&$search="displayName:Pr"&$select=displayName,id
ConsistencyLevel: eventual

Отклик

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

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users(displayName,id)",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Joseph Price",
      "id":"11111111-2222-3333-4444-555555555555"
    },
    {
      "displayName":"Preston Morales",
      "id":"66666666-7777-8888-9999-000000000000"
    }
  ]
}

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

Запрос

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

GET https://graph.microsoft.com/v1.0/groups/{id}/members?$count=true&$filter=startswith(displayName, 'a')
ConsistencyLevel: eventual

Отклик

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

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
  "@odata.count":76,
  "value":[
    {
      "displayName":"AAD Contoso Users",
      "mail":"AADContoso_Users@contoso.com"
    }
  ]
}