Обратная связь Изменить

Список групп

  • Статья
  • Чтение занимает 16 мин

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

Важно!

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

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

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

Разрешения

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

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

HTTP-запрос

GET /groups

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

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

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

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

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

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

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

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

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

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

Отклик

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

Примеры

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

Запрос

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

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

Отклик

Ниже приведен пример ответа.

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

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

{
   "@odata.context":"https://graph.microsoft.com/beta/$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.onmicrosoft.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.onmicrosoft.com",
            "SMTP:golftalk@contoso.com"
         ],
         "renewedDateTime":"2018-11-19T20:29:40Z",
         "resourceBehaviorOptions":[
         ],
         "resourceProvisioningOptions":[
         ],
         "securityEnabled":false,
         "theme":null,
         "visibility":null,
         "onPremisesProvisioningErrors":[
         ]
      }
   ]
}

Пример 2. Получение отфильтрованного списка групп, включая количество возвращаемых объектов

Запрос

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

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

GET https://graph.microsoft.com/beta/groups?$count=true&$filter=hasMembersWithLicenseErrors+eq+true&$select=id,displayName
ConsistencyLevel: eventual

Отклик

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

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

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups(id,displayName)",
   "@odata.count":2,
   "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 см. в статье Расширенные возможности запросов для объектов каталога Azure AD.

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

GET https://graph.microsoft.com/beta/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 см. в статье Расширенные возможности запросов для объектов каталога Azure AD.

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

GET https://graph.microsoft.com/beta/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/beta/$metadata#groups",
   "@odata.count":1,
   "value":[
      {
         "displayName":"a",
         "mailNickname":"a241"
      }
   ]
}

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

Запрос

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

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

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

Отклик

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

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

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

{
   "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
   "@odata.count":1396,
   "value":[
      {
         "displayName":"SFA Videos",
         "mail":"SFAVideos@service.contoso.com",
         "mailNickname":"SFAVideos"
      }
   ]
}

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

Запрос

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

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

GET https://graph.microsoft.com/beta/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/beta/$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"
      }
   ]
}

Пример 7. Перечисление динамических групп

Запрос

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

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

GET https://graph.microsoft.com/beta/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

Отклик

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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"
        }
    ]
}

Пример 8. Перечисление любых групп с любыми лицензиями

Запрос

GET https://graph.microsoft.com/beta/groups?$select=id,assignedLicenses&$filter=assignedLicenses/any()

Отклик

Ниже приведен пример ответа.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups(id,assignedLicenses)",
    "value": [
        {
            "id": "5caf712c-8483-4b3d-8384-d8da988c0ca4",
            "assignedLicenses": [
                {
                    "disabledPlans": [],
                    "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
                }
            ]
        },
        {
            "id": "aae8ec2a-5a08-4013-ae70-fafbb5c20de1",
            "assignedLicenses": [
                {
                    "disabledPlans": [
                        "7547a3fe-08ee-4ccb-b430-5077c5041653"
                    ],
                    "skuId": "18181a46-0d4e-45cd-891e-60aabd171b4e"
                }
            ]
        },
        {
            "id": "e55bdaa0-e104-479a-979e-b0457fff6380",
            "assignedLicenses": [
                {
                    "disabledPlans": [
                        "7547a3fe-08ee-4ccb-b430-5077c5041653"
                    ],
                    "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
                }
            ]
        }
    ]
}