添加成员

命名空间:microsoft.graph

将成员添加到安全或Microsoft 365 组。 使用 API 在一个请求中添加多个成员时,最多只能添加 20 个成员。

下表显示了可添加到安全组或 Microsoft 365 组的成员类型。

对象类型 安全组成员 Microsoft 365 组成员
User 可以是组成员 可以是组成员
安全组 可以是组成员 不能是组成员
Microsoft 365 组 不能是组成员 不能是组成员
设备 可以是组成员 不能是组成员
服务主体 可以是组成员 不能是组成员
组织联系人 可以是组成员 不能是组成员

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

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

权限

下表显示了调用此 API 时,每种资源类型所需的最低特权权限。 若要了解详细信息,包括如何选择权限的信息,请参阅权限

支持的资源 委派(工作或学校帐户) 委派(个人 Microsoft 帐户) 应用程序
设备 GroupMember.ReadWrite.All 和 Device.ReadWrite.All 不支持。 GroupMember.ReadWrite.All 和 Device.ReadWrite.All
GroupMember.ReadWrite.All 不支持。 GroupMember.ReadWrite.All
orgContact GroupMember.ReadWrite.All 和 OrgContact.Read.All 不支持。 GroupMember.ReadWrite.All 和 OrgContact.Read.All
servicePrincipal GroupMember.ReadWrite.All 和 Application.ReadWrite.All 不支持。 GroupMember.ReadWrite.All 和 Application.ReadWrite.All
用户 GroupMember.ReadWrite.All 不支持。 GroupMember.ReadWrite.All

在委托方案中,还必须为登录用户分配受支持的 Microsoft Entra 角色 或具有角色权限的 microsoft.directory/groups/members/update 自定义角色。 此操作支持以下最低特权角色,但可分配角色的组除外:

  • 组所有者
  • 目录作者
  • 组管理员
  • 标识治理管理员
  • 用户管理员
  • Exchange 管理员 - 仅适用于 Microsoft 365 个组
  • SharePoint 管理员 - 仅适用于 Microsoft 365 个组
  • Teams 管理员 - 仅适用于 Microsoft 365 个组
  • Yammer 管理员 - 仅适用于 Microsoft 365 个组
  • Intune 管理员 - 仅适用于安全组

若要将成员添加到可分配角色的组,还必须为应用分配 RoleManagement.ReadWrite.Directory 权限,并且必须为调用用户分配受支持的Microsoft Entra 角色。 特权角色管理员 是此操作支持的最小特权角色。

HTTP 请求

POST /groups/{group-id}/members/$ref
POST /groups/{group-id}/members/

请求标头

标头
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-type application/json. 必需。

请求正文

使用 /groups/{group-id}/members/$ref 语法时,提供包含 @odata.id 属性的 JSON 对象,并按 ID 引用受支持的组成员对象类型。

使用 /groups/{group-id}/members 语法时,请提供一个 JSON 对象,该对象包含一个 members@odata.bind 属性,该属性具有对支持的组成员对象类型的一个或多个 ID 引用。

如果使用 directoryObjects 引用(即 https://graph.microsoft.com/v1.0/directoryObjects/{id}),则对象类型仍必须是受支持的组成员对象类型。

响应

如果成功,此方法返回 204 No Content 响应代码。 当对象已是组的成员或不支持作为组成员时,它将返回 400 Bad Request 响应代码。 当要添加的对象不存在时,它将返回 404 Not Found 响应代码。

示例

示例 1:将成员添加到组

请求

以下示例演示使用 directoryObjects 引用将成员添加到组的请求。

POST https://graph.microsoft.com/v1.0/groups/{group-id}/members/$ref
Content-type: application/json

{
  "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
}

在请求正文中,提供要添加的 directoryObject、user 或 group 对象的 JSON 表示形式。

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

示例 2:在单个请求中向组添加多个成员

此示例说明了如何在 PATCH 操作中通过 OData 绑定支持向组添加多个成员。 在单个请求中最多可以添加 20 个成员。 不支持 POST 操作。 如果请求正文中存在错误条件,则不添加任何成员,并且返回相应的响应代码。

请求

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

PATCH https://graph.microsoft.com/v1.0/groups/{group-id}
Content-type: application/json

{
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
    ]
}

在请求正文中,提供要添加的 directoryObject、user 或 group 对象的 JSON 表示形式。

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content