Microsoft Graph でのグループの操作

グループとは、Microsoft サービス内またはアプリ内のリソースへのアクセスを共有しているプリンシパルの集合です。 ユーザー、他のグループ、デバイス、アプリケーションなどのさまざまなプリンシパルをグループに含めることができます。 グループを使用すると、個々のプリンシパルでの作業を回避し、リソースへのアクセスの管理を簡素化できます。

Microsoft Graph では、 さまざまな種類のグループとグループ 機能を作成および管理するために、グループ リソースの種類とその関連 API が公開されています。

注:

1. グループは、職場または学校のアカウントでのみ作成できます。 個人用 Microsoft アカウントはグループをサポートしません。
2. Microsoft Graph でのすべてのグループ関連の操作には、管理者の同意が必要です。

Microsoft Entra ID と Microsoft Graph のグループの種類

Microsoft Entra ID では、次の種類のグループがサポートされています。

• Microsoft 365 グループ
• セキュリティ グループ
• メールが有効なセキュリティ グループ
• 配布グループ

注:

Microsoft では、Microsoft Graph を使用して管理または取得できない 動的配布グループ もサポートされています。

Microsoft Graph では、グループの種類は、 groupTypes、 mailEnabled、 securityEnabled プロパティの設定によって識別できます。 次の表は、設定によってグループを区別する方法と、グループの種類を Microsoft Graph グループ API で管理できるかどうかを示しています。

型	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 チーム サイト
• Planner の計画
• Intune デバイス管理

次の JSON オブジェクトは、Microsoft Graph グループ API を呼び出したときのグループのサンプル表現を示しています。

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 Graph での Microsoft 365 グループの概要」を参照してください。

セキュリティ グループとメールが有効なセキュリティ グループ

セキュリティ グループは、リソースへのユーザー アクセスを制御するためのものです。 ユーザーがセキュリティ グループのメンバーであるかどうかを確認することで、そのユーザーがアプリ内のいくつかのセキュア リソースにアクセスしようとしているときに、アプリが承認を判断することができます。 セキュリティ グループには、ユーザー、他のセキュリティ グループ、デバイス、およびサービス プリンシパルをメンバーとして含めることができます。

メールが有効なセキュリティ グループ は、セキュリティ グループと同じ方法で使用されますが、グループ メンバーにメールを送信するために使用できます。 メールが有効なセキュリティ グループは、API を使用して作成または更新することはできません。代わりに、読み取り専用です。 詳細については、「メールが有効なセキュリティ グループの管理」を参照してください。

次の JSON オブジェクトは、Microsoft Graph グループ API を呼び出したときのセキュリティ グループのサンプル表現を示しています。

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 が禁止となります。
• ルール構文では、さまざまな演算子がサポートされています。 詳細については、「サポートされている式の演算子」を参照してください。
• String 型の Value は二重引用符 (") で囲む必要があります。 二重引用符内で二重引用符を回避するには、円記号を使用する必要があります。 式は二重引用符で囲まれていないため、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 のダイナミック メンバーシップ ルール」を参照してください。

注:

ダイナミック メンバーシップ ルールでは、テナントは、1 つ以上のダイナミック グループのメンバーである一意のユーザーごとに、少なくとも Microsoft Entra ID P1 ライセンスが必要です。

その他の種類のグループ

Yammer の Microsoft 365 グループは、Yammer への投稿によりユーザーのコラボレーションを容易にするために使用されます。 この種類のグループは、読み取りの要求で返すことができますが、その投稿に API でアクセスすることはできません。 Yammer 投稿とスレッド フィードがグループで有効になると、既定の Microsoft 365 グループ会話が無効になります。 詳細については、「Yammer 開発者向け API ドキュメント」をご覧ください。

セキュリティと Microsoft 365 グループの追加設定

グループ リソースのプロパティの構成とは別に、グループに対して次の設定を構成することもできます。

設定	適用対象
グループの有効期限	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) のリンクに従って取得したグループのプロファイルを読み取ることができます。

グループでゲスト ユーザーが実行できる操作の詳細については、「メンバーとゲストの既定のアクセス許可を比較する」を参照してください。

グループベースのライセンス

グループ ベースのライセンスを使用して、1 つ以上の製品ライセンスをMicrosoft Entra グループに割り当てることができます。その後、ライセンスはグループのメンバーによって継承され、新しいメンバーによって自動的に継承されます。 メンバーがグループを離れると、それらのライセンスが削除されます。 この機能は、 securityEnabled が true に設定されているセキュリティ グループと Microsoft 365 グループでのみ使用できます。

グループベースのライセンスの詳細については、「Microsoft Entra ID のグループベースのライセンスとは」を参照してください。

メイン データ ストアの外部に格納されているプロパティ

グループ リソース データは主にMicrosoft Entra IDに格納されますが、autoSubscribeNewMembers や allowExternalSenders などのプロパティの一部は Microsoft Exchange に格納されます。 ほとんどの場合、これらのプロパティは、他のグループ プロパティと同じ [作成] または [更新] 要求本文で指定することはできません。

メイン データ ストアの外部に格納されたプロパティも、変更追跡の一部としてサポートされていません。 したがって、これらのプロパティのいずれかに変更を加えた場合、デルタ クエリ応答にオブジェクトが表示されることはありません。

group オブジェクトの次のプロパティは、メイン データ ストアの外部に格納されます: accessType、allowExternalSenders、autoSubscribeNewMembers、cloudLicensing、hideFromAddressLists、hideFromOutlookClients、isFavorite、isSubscribedByMail、unseenConversationsCount、unseenCount、unseenMessagesCount、membershipRuleProcessingStatus、、 isArchived。

一般的なユース ケース

Microsoft Graph を使用すると、グループに対して次の一般的な操作ができます。

ユース ケース	API 操作
グループの作成、グループの特性の管理
新しいグループの作成、既存グループの取得、グループでのプロパティの更新、グループの削除を行います。	新しいグループを作成する グループを一覧表示する グループを更新する グループを削除する 有効期限が近いグループを更新する 削除された Microsoft 365 グループを復元する
グループ メンバーシップと所有権を管理する
グループのメンバーを一覧表示し、メンバーを追加または削除します。	メンバーを一覧表示する メンバーを追加する メンバーを削除する
ユーザーがグループのメンバーであるかどうかを判別し、ユーザーがメンバーであるすべてのグループを取得します。	メンバー グループをチェックする メンバー グループを取得する
グループの所有者を一覧表示し、所有者を追加または削除します。	所有者を一覧表示する Add owner 所有者を削除する
Microsoft 365 アプリのグループ機能
グループ会話を管理する	作成、 取得、または 削除
グループ予定表で予定表イベントをスケジュールおよび管理する	作成、 一覧表示、 取得、 更新、 削除
グループの OneNote ノートブックを管理する	作成、 一覧表示
Microsoft Teamsの Microsoft グループを有効にする	Create

グループを管理するためのMicrosoft Entraロール

委任されたシナリオでグループを管理するには、アプリに適切な Microsoft Graph アクセス許可が付与され、サインインユーザーがサポートされているMicrosoft Entraロールである必要があります。

次のMicrosoft Entraロールは、ロール割り当て可能なグループを除き、Microsoft Graph を通じてグループに対するすべての読み取りおよび書き込み操作の最小特権ロールです。 ロール割り当て可能なグループを管理するための最小特権ロールは、 特権ロール管理者です。

• ディレクトリ製作者
• グループ管理者
• ユーザー管理者

さまざまなグループ関連タスクの最小特権管理者ロールの概要については、「グループを 管理するための最小特権ロール」を参照してください。

グループ関連タスクのカスタム ロールを作成することもできます。 Microsoft Entra組み込みロールリファレンスを参照して、アクセス許可固有のタスクを推論するmicrosoft.directory/groups/で始まるアクセス許可を特定し、選択したアクセス許可を持つカスタム ロールを作成します。

次の手順

グループの操作を開始する