在 Microsoft Graph 中使用组

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

Microsoft Graph 公开 组资源类型 及其关联的 API，以创建和管理不同类型的组和组功能。

注意

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

在 Microsoft Entra ID 和 Microsoft Graph 中对类型进行分组

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

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

注意

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

在 Microsoft Graph 中，组的类型可以通过其 groupTypes、 mailEnabled 和 securityEnabled 属性的设置来标识。 下表说明如何按设置区分组，以及组类型是否可以通过 Microsoft Graph 组 API 进行管理。

类型	groupTypes	mailEnabled	securityEnabled	通过组 API 创建和管理
Microsoft 365 组	["Unified"]	true	true 或 false	可访问
安全组	[]	false	true	是
启用邮件的安全组	[]	true	true	不;通过 Microsoft Graph 只读
通讯组	[]	true	false	不;通过 Microsoft Graph 只读

有关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 组概述。

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

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

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

以下 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 组
Device
服务主体
组织联系人

动态成员身份

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中组合多个表达式。

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

CLI

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

Go

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

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

注意

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

其他类型的组

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

安全和Microsoft 365 组的其他设置

除了在组资源上配置属性外，还可以为组配置以下设置。

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组，然后这些许可证由组的成员继承，由任何新成员自动继承。 当成员离开组时，这些许可证将被删除。 此功能只能与安全组和Microsoft将 securityEnabled 设置为 true的 365 个组一起使用。

若要详细了解基于组的许可，请参阅什么是Microsoft Entra ID中基于组的许可？。

常见用例

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

用例	API 操作
创建组、管理组特征
创建新组、获取现有组、更新组的属性和删除组。	新建组 列出组 更新组 删除组 续订 即将过期的组 还原 已删除Microsoft 365 个组
管理组成员身份和所有权
列出组中的成员，并添加或删除成员。	列出成员 添加成员 删除成员
确定用户是否是组成员，并获取用户所属的全部组。	检查成员组 获取成员组
列出组的所有者，并添加或删除所有者。	List owners 添加所有者 Remove owner
Microsoft 365 应用的组功能
管理组对话	创建、获取或删除
在组日历上计划和管理日历事件	创建、 列出、 获取、 更新、 删除
管理组的 OneNote 笔记本	创建， 列出
为 Microsoft Teams 启用Microsoft组	创建

用于管理组的Microsoft Entra角色

若要在委派方案中管理组，必须向应用授予相应的 Microsoft Graph 权限，并且登录用户必须具有受支持的Microsoft Entra角色。

以下Microsoft Entra角色是通过 Microsoft Graph 对组执行的所有读取和写入操作的最低特权角色，但可分配角色的组除外。 用于管理可分配角色的组的最低特权角色是 特权角色管理员。

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

有关不同组相关任务的最低特权管理员角色的摘要，请参阅 管理组的最低特权角色。

还可以为与组相关的任务创建自定义角色。 请参阅Microsoft Entra内置角色参考，确定从microsoft.directory/groups/哪些权限开始推断特定于权限的任务的权限，并使用所选权限创建自定义角色。

后续步骤

开始使用组