Обновление группы

Пространство имен: microsoft.graph

Обновление свойств объекта группы .

Примечание.

members@odata.bind При добавлении участников через PATCH, этот запрос может иметь задержки репликации для недавно созданных групп. Полная репликация объекта группы между репликами каталогов Microsoft Entra ID может занять короткое время. В течение этого окна запросы на добавление участников в группу могут возвращать 400 Bad Request ошибку с сообщением: "Исходный объект ресурса или один из объектов, на которые делается ссылка, не существует".

Чтобы устранить это поведение:

• Повторите попытку после небольшой задержки — подождите несколько секунд и повторите запрос. Задержка обычно небольшая.

Дополнительные сведения см. в разделе Проектирование для обеспечения согласованности для Microsoft Entra.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальное обслуживание	Правительство США L4	Правительство США L5 (DOD)	Китай, обслуживаемый 21Vianet
✅	✅	✅	✅

Разрешения

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

Тип разрешения	Разрешения с наименьшим объемом привилегий	Разрешения с более высоким уровнем привилегий
Делегированные (рабочая или учебная учетная запись)	Group-NestingSupport.ReadWrite.All	Directory.ReadWrite.All, Group-PreferredDataLocation.ReadWrite.All, Group.ManageProtection.All, Group.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.	Не поддерживается.
Приложение	Group-NestingSupport.ReadWrite.All	Directory.ReadWrite.All, Group-PreferredDataLocation.ReadWrite.All, Group.ManageProtection.All, Group.ReadWrite.All

Разрешения для определенных сценариев

• Group-NestingSupport.ReadWrite.All — это разрешение с наименьшими правами на обновление свойства disableNesting .

• Делегированное разрешение Group.ManageProtection.All — это делегированное разрешение с наименьшим объемом привилегий для обновления свойства assignedLabels для облачных групп безопасности. Сценарии, содержащие только приложение, не поддерживаются.

HTTP-запрос

PATCH /groups/{id}

Заголовки запросов

Имя	Тип	Описание
Authorization	string	Bearer {token}. Обязательно. Дополнительные сведения об аутентификации и авторизации.

Текст запроса

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

В следующей таблице указаны свойства, которые можно обновить.

Свойство	Тип	Описание
allowExternalSenders	Логический	Значение по умолчанию: false. Указывает, могут ли пользователи за пределами организации отправлять сообщения в группу.
assignedLabels	Коллекция assignedLabel	Список пар меток конфиденциальности (идентификатор метки, имя метки), связанных с группой Microsoft 365 или облачной группой безопасности. Требуется лицензия Microsoft Entra ID P1. Это свойство можно указать при создании или обновлении группы. Однако для облачных групп безопасности он является неизменным после настройки. Для групп Microsoft 365 это свойство можно обновлять только в делегированных сценариях, когда вызывающему объекту требуется разрешение Microsoft Graph и поддерживаемая роль администратора. Делегированное разрешение Group.ManageProtection.All — это делегированное разрешение с наименьшим объемом привилегий для обновления этого свойства для облачных групп безопасности. Сценарии, содержащие только приложение, не поддерживаются. См. статью "Ключевые отличия от меток групп Microsoft 365 ", чтобы узнать больше об управлении этим свойством для Microsoft 365 и облачных групп безопасности.
autoSubscribeNewMembers	Логический	Значение по умолчанию: false. Указывает, будут ли новые участники группы автоматически подписаны на получение уведомлений по электронной почте. AutoSubscribeNewMembers не может быть true, если в группе установлено false для subscriptionEnabled.
description	String	Необязательное описание для группы.
displayName	String	Отображаемое имя для группы. Это свойство необходимо при создании группы и не может быть очищено во время обновления.
mailNickname	String	Почтовый псевдоним для группы, уникальный для групп Microsoft 365 в организации. Максимальная длина: 64 символа. Это свойство может содержать только символы из набора символов ASCII от 0 до 127, за исключением следующих: @ () \ [] " ; : . <> , SPACE.
preferredDataLocation	String	Предпочтительное расположение данных для группы Microsoft 365. Чтобы обновить это свойство, вызывающему пользователю должна быть назначена по крайней мере одна из следующих ролей Microsoft Entra: Администратор учетных записей пользователей Редактор каталогов Администратор Exchange Администратор SharePoint Дополнительные сведения об этом свойстве см. в статье OneDrive Online с поддержкой нескольких регионов.
securityEnabled	Логический	Указывает, является ли эта группа группой безопасности.
uniqueName	Строка	Уникальный идентификатор, который можно назначить группе и использовать в качестве альтернативного ключа. Может быть обновлен только в том случае, если null и является неизменяемым после настройки.
visibility	String	Определяет видимость группы Microsoft 365. Возможные значения: Private (частная), Public (общедоступная) или пустое значение (оно обрабатывается как Public).

Важно!

• Чтобы обновить эти свойства (accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount), необходимо:
  • Укажите их в своем запросе PATCH, не включая другие свойства из предыдущей таблицы
  • Имеют разрешение Group.ReadWrite.All (Directory.ReadWrite.All для этих свойств не поддерживается)
• Только часть API группы, относящаяся к администрированию и управлению основной группой, поддерживает разрешения приложений и делегированные разрешения. Все остальные участники API группы, включая обновление autoSubscribeNewMembers, поддерживают только делегированные разрешения.
• Правила обновления групп безопасности, поддерживающих почту, в Microsoft Exchange Server могут быть сложными. Дополнительные сведения см. в статье Управление группами безопасности с поддержкой электронной почты в Exchange Server.
• Разрешения приложений не поддерживаются при обновлении assignedLabels. Group.ManageProtection.All — это разрешение с наименьшими правами на обновление assignedLabels для облачных групп безопасности.

Управление расширениями и связанными данными

Используйте этот API для управления каталогом, схемой и открытыми расширениями и их данными для пользователей следующим образом:

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

Отклик

В случае успеха этот метод возвращает код ответа 204 No Content , за исключением 200 OK кода ответа при обновлении следующих свойств: accessType, allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount.

Ошибки

Код состояния	Код ошибки	Сообщение об ошибке	Описание
400 Bad Request	Request_BadRequest	"Исходный ресурсный объект или один из объектов, на который делается ссылка, не существует".	Эта группа была создана недавно и не полностью реплицируется во всех репликах каталогов. Эта ошибка характерна для операций записи ссылок (добавление участников через members@odata.bind). Повторите запрос после небольшой задержки.

Пример

В примере ниже показано, как обновить группу.

Запрос

Ниже показан пример запроса.

HTTP

PATCH https://graph.microsoft.com/v1.0/groups/0d09007d-45b2-458c-b180-880dde3a302e
Content-type: application/json

{
  "description": "Library Assist - ADC",
  "displayName": "Library Assist - ADC",
  "mailNickname": "library-help-adc"
}

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 = "Library Assist - ADC",
	DisplayName = "Library Assist - ADC",
	MailNickname = "library-help-adc",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);

Подробнее о том, как добавить 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 := "Library Assist - ADC"
requestBody.SetDescription(&description) 
displayName := "Library Assist - ADC"
requestBody.SetDisplayName(&displayName) 
mailNickname := "library-help-adc"
requestBody.SetMailNickname(&mailNickname) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().ByGroupId("group-id").Patch(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("Library Assist - ADC");
group.setDisplayName("Library Assist - ADC");
group.setMailNickname("library-help-adc");
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
  description: 'Library Assist - ADC',
  displayName: 'Library Assist - ADC',
  mailNickname: 'library-help-adc'
};

await client.api('/groups/0d09007d-45b2-458c-b180-880dde3a302e')
	.update(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('Library Assist - ADC');
$requestBody->setDisplayName('Library Assist - ADC');
$requestBody->setMailNickname('library-help-adc');

$result = $graphServiceClient->groups()->byGroupId('group-id')->patch($requestBody)->wait();

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

PowerShell

Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Library Assist - ADC"
	displayName = "Library Assist - ADC"
	mailNickname = "library-help-adc"
}

Update-MgGroup -GroupId $groupId -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 = "Library Assist - ADC",
	display_name = "Library Assist - ADC",
	mail_nickname = "library-help-adc",
)

result = await graph_client.groups.by_group_id('group-id').patch(request_body)

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

Отклик

Ниже приводится пример отклика.

HTTP/1.1 204 No Content