通过

List group members

命名空间：microsoft.graph

获取 组的 直接成员列表。 组可将用户、组织联系人、设备、服务主体和其他组作为成员。 此操作不可传递。

重要

此 API 存在一个已知问题，即服务主体未在 v1.0 中列为组成员。 解决方法是，在终结点上 beta 使用此 API 或使用 /groups/{id}?$expand=members API。 有关详细信息，请参阅相关的 已知问题。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

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

重要

当应用程序查询返回 directoryObject 类型集合的关系时，如果它没有读取特定资源类型的权限，则会返回该类型的成员，但信息有限。 例如，仅返回对象类型和 ID 的 @odata.type 属性，而其他属性则指示为 null。 通过此行为，应用程序可以请求所需的最低特权权限，而不是依赖于 目录集。*权限。 有关详细信息，请参阅为不可访问的成员对象返回有限的信息。

在委托方案中，还必须为登录用户分配受支持的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、、$count、$select、 $search$top和 $expandOData 查询参数，以帮助自定义响应。

  • 已启用 OData 强制转换。 例如， /groups/{id}/members/microsoft.graph.user 检索属于用户的组成员。
  • $search 仅在 displayName 和 description 属性上受支持。
  • 只有高级查询参数支持将查询参数用于此 API（不包括 $expand）。 $expand 不支持高级查询参数。 有关详细信息，请参阅 目录对象的高级查询功能。

默认和最大页面大小分别为 100 个和 999 个组对象。

请求标头

标头 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
ConsistencyLevel 最终。 使用 $search、$filter、$orderby 或 OData 强制转换查询参数时，此标头和 $count 是必需的。 它使用的索引可能与对象的最新更改不同步。

请求正文

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

响应

如果成功，此方法会在响应正文中返回 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：使用 $search 和 OData 强制转换获取显示名称中包含字母“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 来获取显示名称以字母 “A” 开头（包括返回的对象数目）的组会员资格

请求

以下示例显示了一个请求。

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"
    }
  ]
}