在 Microsoft Graph 中管理组

Microsoft Graph 中的组是共享资源访问权限的用户、设备或应用程序等主体的容器。 它们通过对主体进行分组(而不是单独管理主体)简化了访问管理。

Microsoft Graph 中的 组资源类型 提供了用于创建和管理支持的组类型及其功能的 API。

注意

  • 只能使用工作或学校帐户创建组。 个人 Microsoft 帐户不支持组。
  • Microsoft Graph 中的所有组相关作都需要管理员同意。

Microsoft Graph 中支持的组类型

Microsoft Graph 支持以下类型的组:

注意

Microsoft Graph 不支持动态通讯组

下表显示了如何使用组的属性识别组类型,以及它们是否可以通过 Microsoft Graph 组 API 进行管理。 核心区别是组的 groupTypesmailEnabledsecurityEnabled 属性中的值。

类型 groupTypes mailEnabled securityEnabled 通过 Microsoft Graph 进行管理
Microsoft 365 组 ["Unified"] true truefalse 可访问
安全组 [] false true
启用邮件的安全组 [] true true 无 (只读)
通讯组 [] true false 无 (只读)

有关详细信息,请参阅比较Microsoft Entra ID中的组

Microsoft 365 组

Microsoft 365 组设计用于协作,并提供对共享资源的访问权限,例如:

  • Outlook 对话和日历。
  • SharePoint 文件和团队网站。
  • OneNote 笔记本。
  • Planner计划。
  • Intune设备管理。

下面是 JSON 格式的 Microsoft 365 组的示例:

HTTP/1.1 201 Created
Content-type: application/json

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "4c5ee71b-e6a5-4343-9e2c-4244bc7e0938",
    "displayName": "OutlookGroup101",
    "groupTypes": ["Unified"],
    "mailEnabled": true,
    "securityEnabled": false,
    "mail": "outlookgroup101@service.microsoft.com",
    "visibility": "Public"
}

若要了解有关Microsoft 365 组的详细信息,请参阅 Microsoft Graph 中的Microsoft 365 组概述

安全组和启用邮件的安全组

安全组 控制对资源的访问。 它们可以包括用户、其他组、设备和服务主体。

启用邮件的安全组 的功能类似于安全组,但也允许电子邮件通信。 这些组在 Microsoft Graph 中是只读的。 有关详细信息,请参阅管理启用邮件的安全组

JSON 格式的安全组示例:

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mailEnabled": false,
    "securityEnabled": true
}

组成员身份

组可以具有静态或动态成员身份。 动态成员身份使用规则根据成员的属性自动添加或删除成员。 并非所有对象类型都可以是 Microsoft 365 和安全组的成员。

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

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

动态成员身份

动态成员身份意味着会根据主体的属性在组中添加或删除主体。 例如,可以将组设置为包含“市场营销”部门中的所有用户。 将用户添加到该部门后,会自动将其添加到组中。 同样,如果用户离开部门,他们将被从组中删除。

只有用户和设备才能是动态组的成员。 动态成员身份需要动态组中每个唯一用户的 Microsoft Entra ID P1 许可证。

成员身份规则是使用Microsoft Entra ID动态组规则语法定义的。

动态成员身份规则的示例:

"membershipRule": "user.department -eq \"Marketing\""

动态成员身份需要 "DynamicMembership"groupTypes 属性中的 值。 可以通过 membershipRuleProcessingState 属性打开或关闭动态成员身份规则。 可以将组从静态成员身份更新为动态成员身份。

创建动态Microsoft 365 组的示例请求:

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mailEnabled": true,
    "mailNickname": "marketing",
    "securityEnabled": false,
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "on"
}

请求在响应正文中返回响应 201 Created 代码和新创建的组对象。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "6f7cd676-5445-47c4-9c2b-c47da4671da2",
    "createdDateTime": "2023-01-20T07:00:31Z",
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mail": "marketing@contoso.com",
    "mailEnabled": true,
    "mailNickname": "marketing",
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "On"
}

其他组设置

可以为组配置其他设置,例如:

Setting 适用对象
组过期 Microsoft 365 组
组设置 Microsoft 365 组
本地同步设置 安全性和Microsoft 365 组

组织中来宾的组搜索限制

应用可以通过查询 /groups 资源 ((例如 https://graph.microsoft.com/beta/groups ,) )来搜索组织目录中的组。 此功能可供管理员和成员使用,但不适用于来宾。

来宾,根据授予应用的权限,可以查看特定组的配置文件 (例如 https://graph.microsoft.com/beta/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc ,) 。 但是,他们无法对 /groups 返回多个结果的资源执行查询。

成员通常对组资源具有更广泛的访问权限,而来宾具有受限的权限,从而限制了他们对某些组功能的访问权限。 有关详细信息,请参阅 比较成员和来宾默认权限

借助适当的权限,应用可以通过导航属性(如 ) /groups/{id}/members访问组配置文件。

基于组的许可

基于组的许可允许将一个或多个产品许可证分配给Microsoft Entra组。 组成员(包括任何新成员)会自动继承许可证。 当成员离开组时,其许可证会自动删除。 此功能仅适用于安全组和将 securityEnabled 设置为 true的Microsoft 365 组。

有关详细信息,请参阅什么是Microsoft Entra ID中基于组的许可?

存储在main数据存储外部的属性

大多数组资源数据存储在 Microsoft Entra ID 中,但某些属性(如 autoSubscribeNewMembersallowExternalSenders)存储在 Microsoft Exchange 中。 这些属性不能包含在与其他组属性相同的“创建”或“更新”请求正文中。

此外,不支持在 main 数据存储外部存储的属性进行更改跟踪。 对这些属性的更改不会显示在增量查询响应中。

以下组属性存储在main数据存储之外:
accessTypeallowExternalSendersautoSubscribeNewMemberscloudLicensinghideFromAddressListshideFromOutlookClientsisFavoriteisSubscribedByMailunseenConversationsCountunseenCountunseenMessagesCountmembershipRuleProcessingStatusisArchived

组 API 的常见用例

Microsoft图形组 API 支持以下常见作:

用例 API作
创建和管理组 创建列出更新删除
管理组成员身份 列出成员添加成员删除成员
管理组所有权 列出所有者添加所有者删除所有者
Microsoft 365 组功能 管理对话日历事件OneNote 笔记本启用 Teams

用于管理组的Microsoft Entra角色

若要管理组,已登录用户必须具有相应的Microsoft Graph 权限,并为其分配受支持的Microsoft Entra角色

用于管理组的最小特权角色包括:

  • 目录作者
  • 组管理员
  • 用户管理员

有关详细信息,请参阅 用于管理组的最低特权角色

后续步骤