Microsoft Graph でのグループの操作
グループとは、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/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 グループを作成します。
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"
}
要求は、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 Graph を使用すると、グループに対して次の一般的な操作ができます。
ユース ケース | API 操作 |
---|---|
グループの作成、グループの特性の管理 | |
新しいグループの作成、既存グループの取得、グループでのプロパティの更新、グループの削除を行います。 |
新しいグループを作成する グループを一覧表示する グループを更新する グループを削除する 有効期限が近いグループを更新する 削除された Microsoft 365 グループを復元する |
グループ メンバーシップと所有権を管理する | |
グループのメンバーを一覧表示し、メンバーを追加または削除します。 |
メンバーを一覧表示する メンバーを追加する メンバーを削除する |
ユーザーがグループのメンバーであるかどうかを判別し、ユーザーがメンバーであるすべてのグループを取得します。 |
メンバー グループをチェックする メンバー グループを取得する |
グループの所有者を一覧表示し、所有者を追加または削除します。 |
所有者を一覧表示する Add owner 所有者を削除する |
Microsoft 365 アプリのグループ機能 | |
グループ会話を管理する | 作成、 取得、または 削除 |
グループ予定表で予定表イベントをスケジュールおよび管理する | 作成、 一覧表示、 取得、 更新、 削除 |
グループの OneNote ノートブックを管理する | 作成、 一覧表示 |
Microsoft Teamsの Microsoft グループを有効にする | Create |
グループを管理するための Microsoft Entra ロール
委任されたシナリオでグループを管理するには、アプリに適切なアクセス許可が付与され、サインインしているユーザーがサポートされている Microsoft Entra ロールである必要があります。
次の Microsoft Entra ロールは、ロール割り当て可能なグループを除き、Microsoft Graph を通じてグループのすべての側面を管理するための最小特権ロールです。 ロール割り当て可能なグループを管理するための最小特権ロールは、 特権ロール管理者です。
- ディレクトリ製作者
- グループ管理者
- ユーザー管理者