Microsoft Graph のグループは、リソースへのアクセスを共有するユーザー、デバイス、アプリケーションなどのプリンシパル用のコンテナーです。 個々に管理するのではなく、プリンシパルをグループ化することで、アクセス管理を容易にします。
Microsoft Graph の グループ リソースの種類 には、サポートされているグループの種類とその機能を作成および管理するための API が用意されています。
注:
- グループは、職場または学校のアカウントを使用してのみ作成できます。 個人用 Microsoft アカウントはグループをサポートしません。
- Microsoft Graph のすべてのグループ関連の操作には、管理者の同意が必要です。
Microsoft Graph でサポートされているグループの種類
Microsoft Graph では、次の種類のグループがサポートされています。
- Microsoft 365 グループ
- セキュリティ グループ
- メールが有効なセキュリティ グループ
- 配布グループ
注:
動的配布グループ は、Microsoft Graph ではサポートされていません。
次の表は、プロパティを使用してグループの種類を識別する方法と、Microsoft Graph グループ API を使用して管理できるかどうかを示しています。 主要な差別化要因は、 グループの groupTypes、 mailEnabled、 securityEnabled プロパティの値です。
| 型 | groupTypes | mailEnabled | securityEnabled | Microsoft Graph を使用して管理する |
|---|---|---|---|---|
| Microsoft 365 グループ | ["Unified"] |
true |
true または false |
はい |
| セキュリティ グループ | [] |
false |
true |
はい |
| メールが有効なセキュリティ グループ | [] |
true |
true |
いいえ (読み取り専用) |
| 配布グループ | [] |
true |
false |
いいえ (読み取り専用) |
詳細については、「Microsoft Entra IDでのグループの比較」を参照してください。
Microsoft 365 グループ
Microsoft 365 グループはコラボレーション用に設計されており、次のような共有リソースへのアクセスを提供します。
- Outlook の会話と予定表。
- SharePoint ファイルとチーム サイト。
- OneNote ノートブック。
- Planner プラン。
- Intuneデバイス管理。
JSON 形式の Microsoft 365 グループの例を次に示します。
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",
"displayName": "OutlookGroup101",
"groupTypes": ["Unified"],
"mailEnabled": true,
"securityEnabled": false,
"mail": "outlookgroup101@service.microsoft.com",
"visibility": "Public"
}
Microsoft 365 グループの詳細については、「Microsoft Graph のMicrosoft 365 グループの概要」を参照してください。
セキュリティ グループとメールが有効なセキュリティ グループ
セキュリティ グループは 、リソースへのアクセスを制御します。 ユーザー、他のグループ、デバイス、サービス プリンシパルを含めることができます。
メールが有効なセキュリティ グループ は、セキュリティ グループと同様に機能しますが、メール通信も許可します。 これらのグループは、Microsoft Graph では読み取り専用です。 詳細については、「メールが有効なセキュリティ グループの管理」を参照してください。
JSON 形式のセキュリティ グループの例:
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.type": "#microsoft.graph.group",
"id": "f87faa71-57a8-4c14-91f0-517f54645106",
"displayName": "SecurityGroup101",
"groupTypes": [],
"mailEnabled": false,
"securityEnabled": true
}
グループ所有権
グループには、グループを管理する 1 人以上の所有者を含めることができます。 所有者には、ユーザーまたはサービス プリンシパルを指定できます。 継続性を確保するために、グループに少なくとも 2 人の所有者を割り当てることをお勧めします。
グループ メンバーシップ
グループには、静的または動的メンバーシップを含めることができます。 動的メンバーシップでは、ルールを使用して、プロパティに基づいてメンバーを自動的に追加または削除します。 すべてのオブジェクト型が Microsoft 365 およびセキュリティ グループのメンバーになるわけではありません。
次の表に、セキュリティ グループまたは Microsoft 365 グループのいずれかに追加できるメンバーの種類を示します。
| オブジェクトの種類 | セキュリティ グループのメンバー | Microsoft 365 グループのメンバー |
|---|---|---|
| User |
|
|
| セキュリティ グループ |
|
|
| Microsoft 365 グループ |
|
|
| デバイス |
|
|
| サービス プリンシパル |
|
|
| 組織の連絡先 |
|
|
動的メンバーシップ
動的メンバーシップとは、プリンシパルがプロパティに基づいてグループに追加または削除されていることを意味します。 たとえば、"マーケティング" 部門のすべてのユーザーを含むようにグループを設定できます。 ユーザーがその部署に追加されると、ユーザーは自動的にグループに追加されます。 同様に、ユーザーが部署を離れた場合、ユーザーはグループから削除されます。
動的グループのメンバーにできるのは、ユーザーとデバイスだけです。 動的メンバーシップには、動的グループ内の一意のユーザーごとに Microsoft Entra ID P1 ライセンスが必要です。
メンバーシップルールは、Microsoft Entra ID動的グループルール構文を使用して定義されます。
動的メンバーシップ規則の例:
"membershipRule": "user.department -eq \"Marketing\""
動的メンバーシップには、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"
}
要求は、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"
}
その他のグループ設定
次のようなグループの他の設定を構成できます。
| Setting | 適用対象 |
|---|---|
| グループの有効期限 | Microsoft 365 グループ |
| グループ設定 | Microsoft 365 グループ |
| オンプレミスの同期設定 | セキュリティとMicrosoft 365 グループ |
| 機関の変換元 | セキュリティとMicrosoft 365 グループ |
組織のゲストに対するグループ検索の制限事項
アプリは、/groups リソース (たとえば、https://graph.microsoft.com/beta/groups) を照会することで、organizationのディレクトリ内のグループを検索できます。 この機能は管理者とメンバーが使用できますが、ゲストには使用できません。
ゲストは、アプリに付与されたアクセス許可に応じて、特定のグループのプロファイル (たとえば、 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 に格納されます。 これらのプロパティは、他のグループ プロパティと同じ [作成] または [更新] 要求本文に含めることはできません。
また、メイン データ ストアの外部に格納されているプロパティは 、変更の追跡ではサポートされていません。 これらのプロパティに対する変更は、デルタ クエリ応答には表示されません。
次のグループ プロパティは、メイン データ ストアの外部に格納されます。
accessType、allowExternalSenders、autoSubscribeNewMembers、cloudLicensing、hideFromAddressLists、hideFromOutlookClients、isArchived、isFavorite、isSubscribedByMail、membershipRuleProcessingStatus、unseenConversationsCount、unseenCount、unseenMessagesCount、welcomeMessageEnabled。
グループ API の一般的なユース ケース
Microsoft Graph グループ API では、次の一般的な操作がサポートされています。
| ユース ケース | API 操作 |
|---|---|
| グループの作成と管理 | 作成、 一覧表示、 更新、 削除 |
| グループ メンバーシップを管理する | メンバーの一覧表示、 メンバーの追加、メンバーの 削除 |
| グループの所有権を管理する | 所有者の一覧表示、 所有者の追加、 所有者の削除 |
| Microsoft 365 グループ機能 | Teams の会話、 予定表イベント、 OneNote ノートブックを管理し、 有効にする |
グループを管理するためのMicrosoft Entraロール
グループを管理するには、サインインしているユーザーに適切な Microsoft Graph アクセス許可があり、サポートされているMicrosoft Entraロールまたはサポートされているアクセス許可を持つカスタム ロールが割り当てられている必要があります。 グループ管理者 はグループを管理するための主な役割ですが、 ユーザー管理者、 Exchange 管理者、 ディレクトリライター などの他のロールでは、さまざまなレベルのアクセス許可を持つグループを管理することもできます。
詳細については、「 グループを管理するための最小特権ロール」を参照してください。