グループを更新する

名前空間: microsoft.graph

グループ オブジェクトのプロパティを更新する。

注:

members@odata.bind を使用して PATCH 経由でメンバーを追加すると、この要求で最近作成されたグループのレプリケーションが遅延する可能性があります。 グループ オブジェクトが Microsoft Entra ID ディレクトリ レプリカ間で完全にレプリケートされるまで、少し時間がかかる場合があります。 この期間中に、グループにメンバーを追加する要求を行うと、"ソース リソース オブジェクトまたは参照されているオブジェクトの 1 つが存在しません" というメッセージを含む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
委任 (個人用 Microsoft アカウント)	サポートされていません。	サポートされていません。
アプリケーション	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	ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。

要求本文

要求本文で、更新すべきプロパティの値のみを指定します。 要求本文に含まれない既存のプロパティは、以前の値のままになるか、他のプロパティ値の変化に基づいて再計算されます。

次の表に、更新できるプロパティを示します。

プロパティ	型	説明
allowExternalSenders	Boolean	既定値は false です。 組織外部のユーザーがグループにメッセージを送信できるかどうかを示します。
assignedLabels	assignedLabel コレクション	Microsoft 365 グループまたはクラウド セキュリティ グループに関連付けられている秘密度ラベルのペア (ラベル ID、ラベル名) の一覧。 Microsoft Entra ID P1 ライセンスが必要です。 このプロパティは、グループの作成または更新時に指定できます。 ただし、クラウド セキュリティ グループに対しては、一度設定すると変更できません。 Microsoft 365 グループの場合、このプロパティを更新できるのは、呼び出し元が Microsoft Graph のアクセス許可と サポートされている管理者ロールの両方を必要とする委任されたシナリオのみです。 Group.ManageProtection.All 委任されたアクセス許可は、クラウド セキュリティ グループのこのプロパティを更新するための最小特権アクセス許可です。 アプリのみのシナリオはサポートされていません。 Microsoft 365 とクラウドのセキュリティ グループに対してこのプロパティを管理する方法の詳細については、「 Microsoft 365 グループ ラベル付けとの主な違い 」を参照してください。
autoSubscribeNewMembers	Boolean	既定値は false です。 グループに追加された新しいメンバーが、電子メールの通知を受信するように自動的にサブスクライブされるかどうかを示します。 グループで subscriptionEnabled が false に設定されている場合、autoSubscribeNewMembers は true になることができません。
説明	String	グループに関するオプションの説明。
displayName	文字列	グループの表示名。 このプロパティは、グループの作成時の必須プロパティであり、更新時にクリアすることはできません。
mailNickname	String	組織内の Microsoft 365 グループに対して一意の、グループのメール エイリアス。 最大文字数は 64 文字です。 このプロパティには、 ASCII 文字セット 0 ~ 127 の文字のみを含めることができます。ただし、以下の @ () \ [] " ; : . <> , SPACEを除いたものです。
preferredDataLocation	String	Microsoft 365 グループのデータの優先される場所。 このプロパティを更新するには、呼び出し元ユーザーに次の Microsoft Entra ロールの少なくとも 1 つが割り当てられている必要があります。 ユーザー アカウント管理者 ディレクトリ ライター Exchange 管理者 SharePoint 管理者 このプロパティの詳細については、「OneDrive Online Multi-Geo」 を参照してください。
securityEnabled	ブール値	グループがセキュリティ グループであるかどうかを指定します。
uniqueName	String	グループに割り当てて代替キーとして使用できる一意の識別子。 null場合にのみ更新可能であり、一度設定すると変更できません。
visibility	String	Microsoft 365 グループの表示を指定します。 可能な値は以下のどれかです: Private、Publicまたは empty (これは 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	"ソース リソース オブジェクトまたは参照されているオブジェクトの 1 つは存在しません。"	このグループは最近作成されたものであり、すべてのディレクトリ レプリカで完全にレプリケートされていません。 このエラーは、リンク書き込み操作 ( 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