在 Microsoft Graph 中使用组

项目
10/21/2023

组是在 Microsoft 服务或你的应用中共享资源访问权限的主体集合。不同的主体（如用户、其他组、设备和应用程序）构成组的各个部分。使用组有助于避免使用单个主体，并简化资源的访问管理。

Microsoft Graph 公开组 API，以创建和管理不同类型的组和组功能。

注意

组只能通过工作或学校帐户创建。个人 Microsoft 帐户不支持组。
Microsoft Graph 中所有与组相关的操作都需要征得管理员同意。

Microsoft Entra ID 和 Microsoft Graph 中的分组类型

Microsoft Entra ID 支持以下类型的组。

Microsoft 365 组
安全组
启用邮件功能的安全组
通讯组

注意

Microsoft 还支持无法通过 Microsoft Graph 管理或检索的动态通讯组。

只有 Microsoft 365 和安全组才能通过 Microsoft Graph 组 API 进行管理。 Microsoft Graph 的启用邮件和通讯组为只读模式。

在 Microsoft Graph 中，可以通过设置groupType、mailEnabled和securityEnabled属性来标识组类型，如下表所示。

类型	groupType	mailEnabled	securityEnabled	通过组 API 创建和管理
Microsoft 365 组	`["Unified"]`	`true`	`true` 或 `false`	可访问
安全组	`[]`	`false`	`true`	是
启用邮件的安全组	`[]`	`true`	`true`	否
通讯组	`[]`	`true`	`false`	否

有关组的详细信息，请参阅以下部分。有关Microsoft Entra ID 中的组的详细信息，请参阅比较Microsoft Entra ID 中的组。

Microsoft 365 组

Microsoft 365 组的强大之处在于它的协作本质，它是项目或团队中相互协作的用户的理想之选。它们由组成员共享的资源创建，包括：

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

调用 Microsoft Graph 组 API 时，以下 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",
    "deletedDateTime": null,
    "classification": "MBI",
    "createdDateTime": "2016-08-23T14:46:56Z",
    "description": "This is a group in Outlook",
    "displayName": "OutlookGroup101",
    "groupTypes": [
        "Unified"
    ],
    "mail": "outlookgroup101@service.microsoft.com",
    "mailEnabled": true,
    "mailNickname": "outlookgroup101",
    "preferredLanguage": null,
    "proxyAddresses": [
        "smtp:outlookgroup101@contoso.com",
        "SMTP:outlookgroup101@service.microsoft.com"
    ],
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

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

Microsoft 365 组的设置

除了配置标准组属性外，还可以为 Microsoft 365 组配置以下设置。

组过期
组设置，例如组是否可以将来宾作为成员、允许谁创建组、组名称中允许的字词等。

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

安全组用于控制用户对资源的访问。通过检查用户是否是安全组的成员，应用可以在用户尝试访问应用中的某些安全资源时决定是否授权。安全组的成员可以是用户、其他安全组、设备和服务主体。

启用邮件的安全组 的使用方式与安全组相同，但可用于向组成员发送电子邮件。无法通过 API 创建或更新启用邮件的安全组；相反，它们为只读模式。若要了解更多信息，请参阅 Exchange 文章管理启用邮件的安全组。

以下 JSON 对象显示了调用 Microsoft Graph 组 API 时安全组的示例表示形式。

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

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2016-07-20T09:21:23Z",
    "description": "This group is a Security Group",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "",
    "preferredLanguage": null,
    "proxyAddresses": [],
    "securityEnabled": true
}

组成员身份

组的成员身份可以是静态分配的，也可以是动态的。并非所有对象类型都可以是 Microsoft 365 和安全组的成员。

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

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

动态成员身份

Microsoft 365 和安全组可以具有动态成员身份规则，这些规则根据主体的属性自动在组中添加或删除成员。例如，“营销员工”组可以定义动态成员身份规则，只有其部门属性设置为“市场营销”的用户才能成为该组的成员。在这种情况下，离开部门的任何用户都会自动从组中删除。

仅支持将用户和设备作为动态成员身份组中的成员。可以为设备或用户创建动态成员身份组，但不能同时创建两者。

在创建组期间，通过 membershipRule 属性指定动态成员身份规则。单个表达式遵循以下语法： Property Operator Value。

按照 Property 以下语法定义： object.property。例如 user.department 或 device.accountEnabled。
规则语法支持各种运算符。有关详细信息，请参阅支持的表达式运算符。
Value类型为 String 的必须用双引号 (“) 括起来。必须使用反斜杠来转义双引号中的任何双引号。在Microsoft Entra管理中心使用规则生成器时，此要求不适用，因为表达式未用双引号引起来。

以下示例演示了一个完整的规则。

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

可以使用、 or和 not 运算符在规则and中组合多个表达式。

groupType 属性还必须在"DynamicMembership"集合中包含值。可以通过 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"
}


// 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 文档。


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups create --body '{\
    "description": "Marketing department folks",\
    "displayName": "Marketing department",\
    "groupTypes": [\
        "Unified",\
        "DynamicMembership"\
    ],\
    "mailEnabled": true,\
    "mailNickname": "marketing",\
    "securityEnabled": false,\
    "membershipRule": "user.department -eq \"Marketing\"",\
    "membershipRuleProcessingState": "on"\
}\
'

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



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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) 

groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

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


// 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 文档。


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
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 文档。


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 文档。


from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group

graph_client = GraphServiceClient(credentials, scopes)

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

若要详细了解如何制定成员身份规则，请参阅Microsoft Entra ID 中的组的动态成员身份规则。

注意

动态成员身份规则要求租户对于属于一个或多个动态组的每个唯一用户至少具有Microsoft Entra ID P1 许可证。

其他类型的组

Yammer 中的 Microsoft 365 组用于通过 Yammer 帖子促进用户协作。可以通过读取请求返回这种类型的组，但无法通过 API 访问它们的帖子。如果对组启用了 Yammer 帖子和对话源，将会禁用默认的 Microsoft 365 组对话。若要了解详细信息，请参阅 Yammer 开发人员 API 文档。

组织中来宾用户的组搜索限制

组搜索功能允许应用通过对 /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组。 Microsoft Entra ID 可确保将许可证分配给组的所有成员。任何加入该组的新成员都获得了相应的许可证。他们离开组时，将移除这些许可证。功能只能与安全组和有 securityEnabled=TRUE 的 Microsoft 365 组一起使用。若要详细了解基于组的许可，请参阅什么是Microsoft Entra ID 中的基于组的许可？。

常见用例

使用 Microsoft Graph，可以执行下面的常见操作。

用例	REST 资源	另请参阅
创建组、管理组特征
创建新组、获取现有组、更新组的属性和删除组。目前，只有 Outlook 中的安全组和组才能通过 API 创建。	group	新建组列出组更新组删除组
管理组成员身份
列出组中的成员，并添加或删除成员。	user group	列出成员添加成员删除成员
确定用户是否是组成员，并获取用户所属的全部组。	user 组 servicePrincipal orgContact	检查成员组获取成员组
列出组的所有者，并添加或删除所有者。	user group	列出所有者添加成员删除成员

在 Microsoft Graph 中使用组

Microsoft Entra ID 和 Microsoft Graph 中的分组类型

Microsoft 365 组

Microsoft 365 组的设置

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

组成员身份

动态成员身份

其他类型的组

组织中来宾用户的组搜索限制

基于组的许可

常见用例

反馈

反馈

其他资源