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
}
グループ メンバーシップ
グループには、静的または動的メンバーシップを含めることができます。 動的メンバーシップでは、ルールを使用して、プロパティに基づいてメンバーを自動的に追加または削除します。 すべてのオブジェクト型が 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"
}
その他のグループ設定
次のようなグループの他の設定を構成できます。
設定 | 適用対象 |
---|---|
グループの有効期限 | 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、 isFavorite、 isSubscribedByMail、 unseenConversationsCount、 unseenCount、 unseenMessagesCount、 membershipRuleProcessingStatus、 isArchived。
グループ API の一般的なユース ケース
Microsoft Graph グループ API では、次の一般的な操作がサポートされています。
ユース ケース | API 操作 |
---|---|
グループの作成と管理 | 作成、 一覧表示、 更新、 削除 |
グループ メンバーシップを管理する | メンバーの一覧表示、 メンバーの追加、メンバーの 削除 |
グループの所有権を管理する | 所有者の一覧表示、 所有者の追加、 所有者の削除 |
Microsoft 365 グループ機能 | Teams の会話、 予定表イベント、 OneNote ノートブックを管理し、 有効にする |
グループを管理するためのMicrosoft Entraロール
グループを管理するには、サインインしているユーザーに適切な Microsoft Graph アクセス許可があり、サポートされているMicrosoft Entraロールが割り当てられている必要があります。
グループを管理するための最小特権ロールは次のとおりです。
- ディレクトリ製作者
- グループ管理者
- ユーザー管理者
詳細については、「 グループを管理するための最小特権ロール」を参照してください。