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

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

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

Примечание.

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

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

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

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

Примечание.

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

Через API групп Microsoft Graph можно управлять только Microsoft 365 и группами безопасности. Почтовые группы и группы рассылки доступны только для чтения через 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;
• планы для планировщика;
• средства управления устройствами 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.

Параметры для групп Microsoft 365

Помимо настройки стандартных свойств группы, можно также настроить следующие параметры для групп Microsoft 365.

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

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

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

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

Следующий объект 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 .

Свойство groupType также должно включать "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

// 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.

Go

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.

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

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

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

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

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

Возможности поиска групп позволяют приложению искать любые группы в каталоге организации путем выполнения запросов к ресурсу /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 гарантирует, что лицензии назначены всем участникам группы. Всем новым участникам, присоединившимся к группе, назначаются соответствующие лицензии. При выходе участников из группы эти лицензии удаляются. Эта возможность доступна только для групп безопасности и групп Microsoft 365 с параметром securityEnabled=TRUE. Дополнительные сведения о групповом лицензировании см. в статье Что такое групповое лицензирование в Microsoft Entra ID?.

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

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

Варианты использования	Ресурсы REST	См. также
Создание групп, управление характеристиками групп
Создание новых групп и получение существующих, обновление свойств и удаление групп. В настоящее время с помощью API можно создавать только группы безопасности и группы Outlook.	group	Создание групп Перечисление групп Обновление групп Удаление групп
Управление членством в группах
Перечисление, добавление и удаление членов групп.	user group	Перечисление членов Добавление члена Удаление члена
Проверка членства пользователя в группе, получение всех групп, в которых состоит пользователь.	user group servicePrincipal orgContact	Проверка членства в группах Получение групп пользователя
Перечисление, добавление и удаление владельцев группы.	user group	Перечисление владельцев Добавление члена Удаление члена