在 Microsoft Graph 中管理组

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

{
    "@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
}

组所有权

组可以有一个或多个管理组的所有者。 所有者可以是用户或服务主体。 我们建议将至少两个所有者分配到一个组，以确保连续性。

无所有者组策略

当一个组失去其唯一所有者时，它将成为无所有者，并且无法再有效地进行管理。 使用 ownerlessGroupPolicy 资源配置租户级策略，该策略会自动向无所有者组的活动成员发送可操作通知电子邮件，提示他们接受所有权。 管理员可以使用安全组配置通知持续时间、要通知的最大成员数以及控制所有权资格。 有关详细信息，请参阅 获取无所有者GroupPolicy 和 创建或更新 ownerlessGroupPolicy。

组成员身份

组可以具有静态或动态成员身份。 动态成员身份使用规则根据成员的属性自动添加或删除成员。 并非所有对象类型都可以是 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 组的示例请求：

HTTP

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

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	Description = "Marketing department folks",
	DisplayName = "Marketing department",
	GroupTypes = new List<string>
	{
		"Unified",
		"DynamicMembership",
	},
	MailEnabled = true,
	MailNickname = "marketing",
	SecurityEnabled = false,
	MembershipRule = "user.department -eq \"Marketing\"",
	MembershipRuleProcessingState = "on",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

转到

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewGroup()
description := "Marketing department folks"
requestBody.SetDescription(&description) 
displayName := "Marketing department"
requestBody.SetDisplayName(&displayName) 
groupTypes := []string {
	"Unified",
	"DynamicMembership",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled) 
mailNickname := "marketing"
requestBody.SetMailNickname(&mailNickname) 
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled) 
membershipRule := "user.department -eq \"Marketing\""
requestBody.SetMembershipRule(&membershipRule) 
membershipRuleProcessingState := "on"
requestBody.SetMembershipRuleProcessingState(&membershipRuleProcessingState) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
group.setDescription("Marketing department folks");
group.setDisplayName("Marketing department");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
groupTypes.add("DynamicMembership");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("marketing");
group.setSecurityEnabled(false);
group.setMembershipRule("user.department -eq \"Marketing\"");
group.setMembershipRuleProcessingState("on");
Group result = graphClient.groups().post(group);

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/groups')
	.post(group);

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$requestBody->setDescription('Marketing department folks');
$requestBody->setDisplayName('Marketing department');
$requestBody->setGroupTypes(['Unified', 'DynamicMembership', 	]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('marketing');
$requestBody->setSecurityEnabled(false);
$requestBody->setMembershipRule('user.department -eq \"Marketing\"');
$requestBody->setMembershipRuleProcessingState('on');

$result = $graphServiceClient->groups()->post($requestBody)->wait();

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

PowerShell

Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Marketing department folks"
	displayName = "Marketing department"
	groupTypes = @(
	"Unified"
"DynamicMembership"
)
mailEnabled = $true
mailNickname = "marketing"
securityEnabled = $false
membershipRule = "user.department -eq "Marketing""
membershipRuleProcessingState = "on"
}

New-MgGroup -BodyParameter $params

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
	description = "Marketing department folks",
	display_name = "Marketing department",
	group_types = [
		"Unified",
		"DynamicMembership",
	],
	mail_enabled = True,
	mail_nickname = "marketing",
	security_enabled = False,
	membership_rule = "user.department -eq \"Marketing\"",
	membership_rule_processing_state = "on",
)

result = await graph_client.groups.post(request_body)

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

请求在响应正文中返回响应 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/v1.0/groups ，) ）来搜索组织目录中的组。 此功能可供管理员和成员使用，但不适用于来宾。

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

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

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

基于组的许可

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

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

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

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

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

以下组属性存储在主数据存储之外：
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角色或具有支持权限的自定义角色。 组管理员 是管理组的主要角色，但其他角色（如 用户管理员、 Exchange 管理员和 目录编写者 ）也可以管理具有不同权限级别的组。

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

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

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

后续步骤

开始使用组

另请参阅

• 管理云中的组的最佳做法