Microsoft Graph でのグループの操作

[アーティクル]
01/04/2024

グループとは、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/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"
}

Microsoft 365 グループと管理者の操作性の詳細については、「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/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 のドキュメントを参照してください。


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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 のドキュメントを参照してください。



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


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


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


from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group

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/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 ドキュメント」をご覧ください。

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

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

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

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

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

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

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

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

Microsoft Graph でのグループの操作

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

Microsoft 365 グループ

Microsoft 365 グループの設定

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

グループメンバーシップ

動的メンバーシップ

その他の種類のグループ

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

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

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

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

フィードバック

フィードバック

その他のリソース

Microsoft Graph でのグループの操作

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

Microsoft 365 グループ

Microsoft 365 グループの設定

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

グループ メンバーシップ

動的メンバーシップ

その他の種類のグループ

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

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

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

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

フィードバック

フィードバック

その他のリソース

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

グループメンバーシップ

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

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

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