Управление группами в Microsoft Graph

2025-05-01

Группы в Microsoft Graph — это контейнеры для субъектов, таких как пользователи, устройства или приложения, которые совместно используют доступ к ресурсам. Они упрощают управление доступом, группируя субъекты вместо того, чтобы управлять ими по отдельности.

Тип ресурса группы в Microsoft Graph предоставляет API для создания поддерживаемых типов групп и их функциональных возможностей и управления ими.

Примечание.

Группы можно создавать только с помощью рабочих или учебных учетных записей. Личные учетные записи Майкрософт не поддерживают группы.
Для всех операций, связанных с группами, в Microsoft Graph требуется согласие администратора.

Типы групп, поддерживаемые в Microsoft Graph

Microsoft Graph поддерживает следующие типы групп:

Группы Microsoft 365
Группы безопасности
группы безопасности с включенной поддержкой почты.
Группы рассылки

Примечание.

Динамические группы рассылки не поддерживаются в Microsoft Graph.

В следующей таблице показано, как определить типы групп с помощью их свойств и можно ли управлять ими с помощью API групп Microsoft Graph. Основными отличиями являются значения свойств 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.
Планировщик планов.
Intune управления устройствами.

Ниже приведен пример группы Microsoft 365 в формате JSON:

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

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

Дополнительные сведения о Группы Microsoft 365 см. в статье Обзор Группы Microsoft 365 в Microsoft Graph.

Группы безопасности (обычные и поддерживающие почту)

Группы безопасности управляют доступом к ресурсам. Они могут включать пользователей, другие группы, устройства и субъекты-службы.

Группы безопасности с поддержкой почты работают как группы безопасности, но также разрешают обмен данными по электронной почте. Эти группы доступны только для чтения в 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/beta/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.Beta.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 для Microsoft Graph по умолчанию используют версию API версии 1.0 и поддерживают не все типы, свойства и API, доступные в бета-версии. Дополнительные сведения о доступе к бета-API с помощью SDK см. в статье Использование пакетов Microsoft Graph SDK с бета-API.

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.



mgc-beta 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.



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

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-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.


// 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')
	.version('beta')
	.post(group);

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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.Beta.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-MgBetaGroup -BodyParameter $params

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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/beta/$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": "[email protected]",
    "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 группе. Участники группы, включая всех новых участников, автоматически наследуют эти лицензии. Когда участники покидают группу, их лицензии автоматически удаляются. Эта функция доступна только для групп безопасности и Группы Microsoft 365 с параметром securityEnabled для параметра true.

Дополнительные сведения см. в статье Что такое групповое лицензирование в 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 групп

API групп Microsoft Graph поддерживает следующие распространенные операции:

Вариант использования	Операции API
Создание групп и управление ими	Создание, вывод списка, обновление и удаление
Управление членством в группах	Вывод списка участников, добавление участника и удаление участников
Управление владением группой	Вывод списка владельцев, добавление владельца и удаление владельца
Функциональные возможности группы Microsoft 365	Управление беседами, событиями календаря, записными книжками OneNote и включение для Teams

Microsoft Entra роли для управления группами

Для управления группами вошедшего пользователя должны быть соответствующие разрешения Microsoft Graph и назначена поддерживаемая роль Microsoft Entra.

Ниже перечислены роли с наименьшими привилегиями для управления группами.

Запись каталогов
Администратор групп
Администратор пользователей

Дополнительные сведения см. в разделе Минимальные привилегированные роли для управления группами.

Следующее действие

Начало работы с группами

Поделиться через

Управление группами в Microsoft Graph

Типы групп, поддерживаемые в Microsoft Graph

Группы Microsoft 365

Группы безопасности (обычные и поддерживающие почту)

Участие в группе

Динамическое членство

Другие параметры группы

Ограничения группового поиска для гостей в организациях

Лицензирование на основе групп

Свойства, хранящиеся за пределами хранилища данных main

Распространенные варианты использования API групп

Microsoft Entra роли для управления группами

Следующее действие

Обратная связь

Дополнительные ресурсы