Microsoft Graph でのグループの操作

[アーティクル]
05/23/2024

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

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

注:

グループは、職場または学校のアカウントでのみ作成できます。個人用 Microsoft アカウントはグループをサポートしません。
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/beta/$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"
}

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

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

メールが有効なセキュリティグループ は、セキュリティグループと同じ方法で使用されますが、グループメンバーにメールを送信するために使用できます。メールが有効なセキュリティグループは、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 グループを作成します。

POST https://graph.microsoft.com/beta/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"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.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);

重要

Microsoft Graph SDK では、既定で v1.0 バージョンの API が使用され、ベータ版で使用可能なすべての型、プロパティ、API がサポートされているわけではありません。 SDK を使用してベータ API にアクセスする方法の詳細については、「ベータ API で Microsoft Graph SDK を使用する」を参照してください。

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。



mgc-beta 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 のドキュメントを参照してください。



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-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 のドキュメントを参照してください。


// 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 のドキュメントを参照してください。


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')
	.version('beta')
	.post(group);

重要

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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 のドキュメントを参照してください。


Import-Module Microsoft.Graph.Beta.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-MgBetaGroup -BodyParameter $params

重要

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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/beta/$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/beta/groupsなど) に対してクエリを実行して、アプリで組織のディレクトリ内のグループを検索できるようになります。管理者とメンバーであるユーザーは、どちらもこの機能を使用できますが、ゲストユーザーは使用できません。

サインインしているユーザーがゲストユーザーの場合、アプリに付与されたアクセス許可に応じて、特定のグループのプロファイルを読み取ることができますが (たとえばhttps://graph.microsoft.com/beta/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 に格納されます。ほとんどの場合、これらのプロパティは、他のグループプロパティと同じ [作成] または [更新] 要求本文で指定することはできません。

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

Microsoft Graph グループ API の一般的なユースケース

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/で始まるアクセス許可を特定し、選択したアクセス許可を持つカスタムロールを作成します。

次の手順

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

次の方法で共有

Microsoft Graph でのグループの操作

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

Microsoft 365 グループ

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

グループメンバーシップ

動的メンバーシップ

その他の種類のグループ

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

組織のゲストユーザーに対するユーザーとグループの検索の制限事項

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

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

Microsoft Graph グループ API の一般的なユースケース

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

次の手順

フィードバック

その他のリソース

次の方法で共有

Microsoft Graph でのグループの操作

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

Microsoft 365 グループ

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

グループ メンバーシップ

動的メンバーシップ

その他の種類のグループ

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

組織のゲスト ユーザーに対するユーザーとグループの検索の制限事項

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

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

Microsoft Graph グループ API の一般的なユース ケース

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

次の手順

フィードバック

その他のリソース

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

グループメンバーシップ

組織のゲストユーザーに対するユーザーとグループの検索の制限事項

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

Microsoft Graph グループ API の一般的なユースケース