Microsoft Graph でのグループの操作

[アーティクル]
10/28/2023

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

Microsoft Graph は、さまざまな種類のグループとグループ機能を作成および管理するためのグループ API を公開しています。

注:

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

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

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

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

注:

Microsoft は動的配布グループを Microsoft Graph で管理または取得することもサポートしています。

Microsoft Graph グループ API を使用して管理できるのは、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 チームサイト
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@microsoft.onmicrosoft.com",
        "SMTP:outlookgroup101@service.microsoft.com"
    ],
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

Microsoft 365 グループの詳細については、「Microsoft Graph での Microsoft 365 グループの概要」を参照してください。

Microsoft 365 グループの設定

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

グループの有効期限
グループの設定、ゲストをメンバーにできるかどうか、グループの作成が許可されているユーザー、グループ名で許可されている単語などです。

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

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

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

次の 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 演算子を使用して、ルール内の複数の式を組み合わせることができます。

groupType プロパティには、コレクションの "DynamicMembership" 値も含める必要があります。ダイナミックメンバーシップルールは、membershipRuleProcessingState プロパティを使用してオンまたはオフにできます。割り当てられたメンバーシップがあるグループを更新すると、ダイナミックメンバーシップを所有することができます。

次の要求例では、マーケティング部署の従業員のみを含めることができる新しい Microsoft 365 グループを作成します。

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"
}


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


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



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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Group group = new Group();
group.description = "Marketing department folks";
group.displayName = "Marketing department";
LinkedList<String> groupTypesList = new LinkedList<String>();
groupTypesList.add("Unified");
groupTypesList.add("DynamicMembership");
group.groupTypes = groupTypesList;
group.mailEnabled = true;
group.mailNickname = "marketing";
group.securityEnabled = false;
group.membershipRule = "user.department -eq \"Marketing\"";
group.membershipRuleProcessingState = "on";

graphClient.groups()
	.buildRequest()
	.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')
	.post(group);

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


<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$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.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 のドキュメントを参照してください。


# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

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 のダイナミックメンバーシップルール」を参照してください。

注:

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

その他の種類のグループ

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

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

グループの検索機能を使用すると、/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 グループに 1 つ以上の製品ライセンスを割り当てることができます。 Microsoft Entra ID では、グループのメンバー全員にライセンスが割り当てられていることを確認します。グループに参加する新しいメンバー全員に、適切なライセンスが割り当てられます。グループを脱退するときに、これらのライセンスは削除されます。この機能は、セキュリティグループと securityEnabled=TRUE を持つ Microsoft 365 グループでのみ使用でききます。グループベースのライセンスの詳細については、「Microsoft Entra ID のグループベースのライセンスとは」を参照してください。

一般的なユースケース

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

ユースケース	REST リソース	関連項目
グループの作成、グループの特性の管理
新しいグループの作成、既存グループの取得、グループでのプロパティの更新、グループの削除を行います。現在、API を使用して、セキュリティグループと Outlook 内グループのみを作成できます。	group	新しいグループを作成するグループを一覧表示するグループを更新するグループを削除する
グループメンバーシップを管理する
グループのメンバーを一覧表示し、メンバーを追加または削除します。	user group	メンバーを一覧表示するメンバーを追加するメンバーを削除する
ユーザーがグループのメンバーであるかどうかを判別し、ユーザーがメンバーであるすべてのグループを取得します。	user group servicePrincipal orgContact	メンバーグループをチェックするメンバーグループを取得する
グループの所有者を一覧表示し、所有者を追加または削除します。	user group	所有者を一覧表示するメンバーを追加するメンバーを削除する

新機能

この API セットに関する最新機能や更新プログラムを検索してください。

Microsoft Graph でのグループの操作

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

Microsoft 365 グループ

Microsoft 365 グループの設定

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

グループメンバーシップ

動的メンバーシップ

その他の種類のグループ

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

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

一般的なユースケース

新機能

その他のリソース

その他のリソース

Microsoft Graph でのグループの操作

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

Microsoft 365 グループ

Microsoft 365 グループの設定

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

グループ メンバーシップ

動的メンバーシップ

その他の種類のグループ

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

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

一般的なユース ケース

新機能

その他のリソース

その他のリソース

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

グループメンバーシップ

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

一般的なユースケース