Работа с группами в Microsoft Graph

Группы — это коллекции участников с совместным доступом к ресурсам в службах Майкрософт или ваших приложениях. В состав групп могут входить различные участники, такие как пользователи, другие группы, устройства и приложения. Использование групп помогает избежать работы с отдельными участниками и упрощает управление доступом к ресурсам.

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

Примечание.

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

Типы групп в Microsoft Entra ID и Microsoft Graph

Microsoft Entra ID поддерживает следующие типы групп.

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

Примечание.

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

В Microsoft Graph тип группы можно определить с помощью параметров ее свойств groupTypes, mailEnabled и securityEnabled . В следующей таблице показано, как различать группы по параметрам и можно ли управлять типами групп с помощью API групп Microsoft Graph.

Тип	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;
• планы для планировщика;
• средства управления устройствами Intune.

В следующем объекте JSON показано примерное представление группы при вызове API групп Microsoft Graph.

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 365 в Microsoft Graph.

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

Группы безопасности предназначены для управления доступом пользователей к ресурсам. Проверяя, является ли пользователь членом группы безопасности, приложение может принимать решения касательно авторизации, когда пользователь пытается получить доступ к защищенным ресурсам в приложении. В группы безопасности могут входить пользователи, другие группы безопасности, устройства и субъекты-службы.

Группы безопасности с поддержкой почты используются так же, как и группы безопасности, но могут использоваться для отправки сообщений электронной почты участникам группы. Группы безопасности с включенной поддержкой почты нельзя создавать или обновлять с помощью API. Вместо этого они доступны только для чтения. Дополнительные сведения см. в статье Управление группами безопасности с поддержкой почты.

Следующий объект JSON показывает пример представления группы безопасности при вызове API групп Microsoft Graph.

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\"".

В правиле можно объединить несколько выражений andс помощью операторов , orи not .

Свойство 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 для каждого уникального пользователя, который является членом одной или нескольких динамических групп.

Группы других типов

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

Дополнительные параметры безопасности и групп 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 365, для которых параметр securityEnabled имеет значение true.

Дополнительные сведения о групповом лицензировании см. в статье Что такое групповое лицензирование в Microsoft Entra ID?.

Основные варианты использования

Ниже перечислены некоторые распространенные операции с группами, которые можно выполнять с помощью Microsoft Graph.

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

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

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

Следующие Microsoft Entra роли являются наименее привилегированными для всех операций чтения и записи в группах через Microsoft Graph, за исключением групп, назначаемых ролями. Наименее привилегированной ролью для управления группами, назначаемыми ролями, является администратор привилегированных ролей.

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

Сводка ролей администратора с наименьшими привилегиями для различных задач, связанных с группами, см. в разделе Минимальные привилегированные роли для управления группами.

Вы также можете создавать настраиваемые роли для задач, связанных с группами. См. ссылку на Microsoft Entra ссылку на встроенные роли, чтобы определить разрешения, которые начинаются с microsoft.directory/groups/ определения задач, относящихся к конкретным разрешениям, и создать пользовательскую роль с выбранными разрешениями.

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

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