Список групп

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

Список всех групп , доступных в организации, за исключением динамических групп рассылки. Чтобы получить динамические группы рассылки, используйте центр администрирования Exchange.

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

Примечание.

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

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

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

Разрешения

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

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

HTTP-запрос

GET /groups

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

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

Чтобы показать список только групп Microsoft 365 (т. н. единых групп), примените фильтр для groupTypes:

GET https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/any(c:c+eq+'Unified')

Параметр запроса $search поддерживает разметку только в полях displayName и description, а также требует заголовок ConsistencyLevel. Поля, отличные от displayName и description для $filterstartswith поведения по умолчанию.

Свойства расширения также поддерживают следующие параметры запроса:

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

Дополнительные сведения о параметрах запроса OData см. в статье Параметры запроса OData. Дополнительные сведения об использовании ConsistencyLevel и $count, см. в статье Расширенные возможности запросов к объектам каталога.

Фильтровать по типам групп

Тип группы Запрос API
Группы Microsoft 365 (Unified) GET/groups?$filter=groupTypes/any(c:c+eq+'Unified')
Группы безопасности GET/groups?$filter=mailEnabled eq false&securityEnabled eq true
Группы безопасности, поддерживающие почту ПОЛУЧИТЬ/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq true&$count=true **
Группы рассылки ПОЛУЧИТЬ/groups?$filter=NOT groupTypes/any(c:c eq 'Unified') and mailEnabled eq true and securityEnabled eq false&$count=true **

** : Этот пример поддерживается только расширенными возможностями выполнения запросов.

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

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

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

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

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и коллекцию объектов group в тексте отклика. Отклик включает в себя только свойства по умолчанию для каждой группы.

Примеры

Пример 1. Получение списка групп

Запрос

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

GET https://graph.microsoft.com/v1.0/groups

Отклик

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups",
  "value": [
    {
      "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
      "deletedDateTime": null,
      "classification": null,
      "createdDateTime": "2018-12-22T02:21:05Z",
      "description": "Self help community for golf",
      "displayName": "Golf Assist",
      "expirationDateTime": null,
      "groupTypes": [
        "Unified"
      ],
      "isAssignableToRole": null,
      "mail": "golfassist@contoso.com",
      "mailEnabled": true,
      "mailNickname": "golfassist",
      "membershipRule": null,
      "membershipRuleProcessingState": null,
      "onPremisesLastSyncDateTime": null,
      "onPremisesSecurityIdentifier": null,
      "onPremisesSyncEnabled": null,
      "preferredDataLocation": "CAN",
      "preferredLanguage": null,
      "proxyAddresses": [
        "smtp:golfassist@contoso.com",
        "SMTP:golfassist@contoso.com"
      ],
      "renewedDateTime": "2018-12-22T02:21:05Z",
      "resourceBehaviorOptions": [],
      "resourceProvisioningOptions": [],
      "securityEnabled": false,
      "theme": null,
      "visibility": "Public",
      "onPremisesProvisioningErrors": []
    },
    {
      "id": "d7797254-3084-44d0-99c9-a3b5ab149538",
      "deletedDateTime": null,
      "classification": null,
      "createdDateTime": "2018-11-19T20:29:40Z",
      "description": "Talk about golf",
      "displayName": "Golf Discussion",
      "expirationDateTime": null,
      "groupTypes": [],
      "isAssignableToRole": null,
      "mail": "golftalk@contoso.com",
      "mailEnabled": true,
      "mailNickname": "golftalk",
      "membershipRule": null,
      "membershipRuleProcessingState": null,
      "onPremisesLastSyncDateTime": null,
      "onPremisesSecurityIdentifier": null,
      "onPremisesSyncEnabled": null,
      "preferredDataLocation": "CAN",
      "preferredLanguage": null,
      "proxyAddresses": [
        "smtp:golftalk@contoso.com",
        "SMTP:golftalk@contoso.com"
      ],
      "renewedDateTime": "2018-11-19T20:29:40Z",
      "resourceBehaviorOptions": [],
      "resourceProvisioningOptions": [],
      "securityEnabled": false,
      "serviceProvisioningErrors": [],
      "theme": null,
      "visibility": null,
      "onPremisesProvisioningErrors": []
    }
  ]
}

Пример 2. Получение отфильтрованного списка групп

Этот запрос, фильтрующий по свойству hasMembersWithLicenseErrors , не поддерживает получение количества возвращенных объектов.

Запрос

GET https://graph.microsoft.com/v1.0/groups?$filter=hasMembersWithLicenseErrors+eq+true&$select=id,displayName

Отклик

Ниже приведен пример отклика, содержащего только запрашиваемые свойства.

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

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(id,displayName)",
   "value":[
      {
         "id":"11111111-2222-3333-4444-555555555555",
         "displayName":"Contoso Group 1"
      },
      {
         "id":"22222222-3333-4444-5555-666666666666",
         "displayName":"Contoso Group 2"
      }
   ]
}

Пример 3. Получение только количества групп

Запрос

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

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

GET https://graph.microsoft.com/v1.0/groups/$count
ConsistencyLevel: eventual

Отклик

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

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

893

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

Запрос

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

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

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

Отклик

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

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

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

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
   "@odata.count":1,
   "value":[
      {
         "displayName":"a",
         "mailNickname":"a241"
      }
   ]
}

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

Запрос

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

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

GET https://graph.microsoft.com/v1.0/groups?$search="displayName:Video" OR "description:prod"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

Отклик

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

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

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

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
   "@odata.count":1396,
   "value":[
      {
         "displayName":"SFA Videos",
         "mail":"SFAVideos@service.contoso.com",
         "mailNickname":"SFAVideos"
      },
      {
         "description":"Video Production",
         "displayName":"Video Production",
         "mail":"videoprod@service.contoso.com",
         "mailNickname":"VideoProduction"
      }
   ]
}

Пример 6. Вывод списка динамических групп безопасности

Запрос

В следующем примере показан запрос, который фильтрует по membershipRuleProcessingState для получения динамических групп. Можно также фильтровать свойства groupTypes (то есть $filter=groupTypes/any(s:s eq 'DynamicMembership')). Для этого запроса требуется заглавная строка ConsistencyLevel, установленная для eventual и строки запроса $count=true, так как в запросе используется оператор not параметра запроса $filter. Дополнительные сведения об использовании ConsistencyLevel и $count, см. в статье Расширенные возможности запросов к объектам каталога.

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

GET https://graph.microsoft.com/v1.0/groups?$filter=mailEnabled eq false and securityEnabled eq true and NOT(groupTypes/any(s:s eq 'Unified')) and membershipRuleProcessingState eq 'On'&$count=true&$select=id,membershipRule,membershipRuleProcessingState
ConsistencyLevel: eventual

Отклик

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(id,membershipRule,membershipRuleProcessingState)",
    "@odata.count": 1,
    "value": [
        {
            "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/e9f4a701-e7b5-4401-a0ca-5bd5f3cdcf4b/Microsoft.DirectoryServices.Group",
            "id": "e9f4a701-e7b5-4401-a0ca-5bd5f3cdcf4b",
            "membershipRule": "(user.userType -contains \"Guest\" and user.accountEnabled -eq true) or (user.city -eq \"Nairobi\")",
            "membershipRuleProcessingState": "On"
        }
    ]
}

Пример 7. Составление списка всех групп с любыми лицензиями и получение участников группы

Запрос

GET https://graph.microsoft.com/v1.0/groups?$select=id,assignedLicenses&$filter=assignedLicenses/any()&$expand=members($select=id,displayName)

Отклик

Ниже приводится пример отклика.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(id,assignedLicenses,members())",
  "value": [
    {
      "id": "5caf712c-8483-4b3d-8384-d8da988c0ca4",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
        }
      ],
      "members": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "0952e4c8-432f-4950-a65c-769c45993527"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49e373b6-4717-40c6-ad43-843c45a258f0"
        }
      ]
    },
    {
      "id": "aae8ec2a-5a08-4013-ae70-fafbb5c20de1",
      "assignedLicenses": [
        {
          "disabledPlans": [
            "7547a3fe-08ee-4ccb-b430-5077c5041653"
          ],
          "skuId": "18181a46-0d4e-45cd-891e-60aabd171b4e"
        }
      ],
      "members": []
    }
  ]
}
  • Last updated on