Microsoft Graph 中的组是共享资源访问权限的用户、设备或应用程序等主体的容器。 它们通过对主体进行分组(而不是单独管理主体)简化了访问管理。
Microsoft Graph 中的 组资源类型 提供了用于创建和管理支持的组类型及其功能的 API。
注意
- 只能使用工作或学校帐户创建组。 个人 Microsoft 帐户不支持组。
- Microsoft Graph 中的所有组相关作都需要管理员同意。
Microsoft Graph 中支持的组类型
Microsoft Graph 支持以下类型的组:
- Microsoft 365 组
- 安全组
- 启用邮件功能的安全组
- 通讯组
注意
Microsoft Graph 不支持动态通讯组。
下表显示了如何使用组的属性识别组类型,以及它们是否可以通过 Microsoft Graph 组 API 进行管理。 核心区别是组的 groupTypes、 mailEnabled 和 securityEnabled 属性中的值。
类型 | groupTypes | mailEnabled | securityEnabled | 通过 Microsoft Graph 进行管理 |
---|---|---|---|---|
Microsoft 365 组 | ["Unified"] |
true |
true 或 false |
可访问 |
安全组 | [] |
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 中,但某些属性(如 autoSubscribeNewMembers 和 allowExternalSenders)存储在 Microsoft Exchange 中。 这些属性不能包含在与其他组属性相同的“创建”或“更新”请求正文中。
此外,不支持在 main 数据存储外部存储的属性进行更改跟踪。 对这些属性的更改不会显示在增量查询响应中。
以下组属性存储在main数据存储之外:
accessType、 allowExternalSenders、 autoSubscribeNewMembers、 cloudLicensing、 hideFromAddressLists、 hideFromOutlookClients、 isFavorite、 isSubscribedByMail、 unseenConversationsCount、 unseenCount、 unseenMessagesCount、 membershipRuleProcessingStatus、 isArchived。
组 API 的常见用例
Microsoft图形组 API 支持以下常见作:
用例 | API作 |
---|---|
创建和管理组 | 创建、 列出、 更新和 删除 |
管理组成员身份 | 列出成员、 添加成员和 删除成员 |
管理组所有权 | 列出所有者、 添加所有者和 删除所有者 |
Microsoft 365 组功能 | 管理对话、 日历事件、 OneNote 笔记本并 启用 Teams |
用于管理组的Microsoft Entra角色
若要管理组,已登录用户必须具有相应的Microsoft Graph 权限,并为其分配受支持的Microsoft Entra角色。
用于管理组的最小特权角色包括:
- 目录作者
- 组管理员
- 用户管理员
有关详细信息,请参阅 用于管理组的最低特权角色。