反馈 编辑

列出组

  • 项目

命名空间：microsoft.graph

列出组织中可用的所有组，不包括动态通讯组。 若要检索动态通讯组，请 使用 Exchange 管理中心。

此操作在默认情况下仅返回每个组的一部分属性。 这些默认属性将记录在属性部分中。 若要获取 非 默认返回的属性，请对组执行 GET 操作，并在 $select OData 查询选项中指定属性。 hasMembersWithLicenseErrors 和 isArchived 属性为异常，不会在 $select 查询中返回。

注意： 此请求可能对最近创建、更新或删除的组具有复制延迟。

权限

要调用此 API，需要以下权限之一。要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。
应用程序 GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

HTTP 请求

GET /groups

可选的查询参数

此方法支持使用 $count、$expand、$filter、$orderBy、$search、$select 和 $top OData 查询参数 以帮助自定义响应。 默认和最大页面大小分别为 100 和 999 个组对象。 只有将 ConsistencyLevel 标头设置为 eventual 和 $count 时，才支持某些查询。 有关详细信息，请参阅 Azure AD 目录对象的高级查询功能。

若要仅列出 Microsoft 365 组（亦称为“统一组”），请对 groupTypes 应用筛选器：

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

$search查询参数仅支持对 displayName 和 说明 字段进行标记化，并且需要 ConsistencyLevel 标头。 displayName 和 说明以外的字段 默认为$filter``startswith行为。

有关 OData 查询选项的详细信息，请参阅 OData 查询参数。 有关使用 ConsistencyLevel 和$count的详细信息，请参阅 Azure AD 目录对象的高级查询功能。

检索扩展和关联数据

扩展类型 备注
架构扩展 仅通过 $select 返回。
开放扩展 仅与 $expand一起返回。
目录扩展 默认情况下返回。

请求标头

名称 说明
Authorization Bearer {token}。必需。
ConsistencyLevel 最终。 当使用 $search 或 $filter 的特定用法时，需要此标头和 $count。 有关使用 ConsistencyLevel 和 $count 的详细信息，请参阅 Azure AD 目录对象的高级查询功能。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法在响应正文中返回 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.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/v1.0/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/v1.0/$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/v1.0/groups/$count
ConsistencyLevel: eventual

响应

下面展示了示例响应。

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

893

示例 4：使用 $filter 和 $top 获取显示名称以“a”开头（包括返回的对象数）的组。

请求

下面展示了示例请求。 此请求需要将 ConsistencyLevel 标头设置为 eventual 和 $count=true 查询字符串，因为请求同时具有 $orderBy 和 $filter 查询参数。 有关使用 ConsistencyLevel 和 $count 的详细信息，请参阅 Azure AD 目录对象的高级查询功能。

注意：$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”（包括返回的对象数）的组。

请求

下面展示了示例请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual，因为在请求中有 $search。 有关使用 ConsistencyLevel 和 $count 的详细信息，请参阅 Azure AD 目录对象的高级查询功能。

注意：$count和$search 查询参数当前在 Azure AD B2C 租户中不可用。

GET https://graph.microsoft.com/v1.0/groups?$search="displayName:Video"&$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"
      }
   ]
}

示例 6：使用 $search 获取显示名称中包含字母“Video”或其说明中包含字母“prod”（包括返回的对象数）的组。

请求

下面展示了示例请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual，因为在请求中有 $search。 有关使用 ConsistencyLevel 和 $count 的详细信息，请参阅 Azure AD 目录对象的高级查询功能。

注意：$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"
      }
   ]
}

示例 7：列出动态安全组

请求

下面是按 membershipRuleProcessingState 进行筛选以检索动态组的请求示例。 也可以按 groupTypes 属性 (即 $filter=groupTypes/any(s:s eq 'DynamicMembership')) 进行筛选。 此请求需要将 ConsistencyLevel 标头设置为 eventual 和 $count=true 查询字符串，因为此请求使用了 $filter 查询参数的 not 运算符。 有关使用 ConsistencyLevel 和 $count 的详细信息，请参阅 Azure AD 目录对象的高级查询功能。

注意：$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()

响应

下面展示了示例响应。

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

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