Microsoft Graph でのグループの操作

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

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

注意

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

Azure AD と Microsoft Graph でのグループの種類

Azure Active Directory (Azure AD) は、次のグループの種類をサポートします。

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

注意

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

Microsoft Graph グループ API を使用して管理できるのは、Microsoft 365 グループとセキュリティ グループのみです。 メールが有効なグループと配布グループは、Microsoft Graph を使用して読み取り専用になります。

Microsoft Graph では、グループの種類は、下の表に示す groupTypemailEnabledsecurityEnabled の各プロパティの設定で特定できます。

種類 groupType mailEnabled securityEnabled グループ API 経由で作成および管理
Microsoft 365 グループ ["Unified"] true true または false はい
セキュリティ グループ [] false true はい
メールが有効なセキュリティ グループ [] true true なし
配布グループ [] true false いいえ

グループの詳細については、以下のセクションを参照してください。 Azure AD のグループの詳細については、「Azure AD でのグループの比較」を参照してください。

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

動的メンバーシップ

すべての種類のグループには、プリンシパルのプロパティに基づいてグループから自動的にメンバーを追加または削除するダイナミック メンバーシップ ルールを付けることができます。 たとえば、「マーケティング従業員」グループは、部署プロパティが「マーケティング」に設定されているユーザーのみがグループのメンバーになれるというダイナミック メンバーシップ ルールを定義できます。 この場合、部署を離れるユーザーはグループから自動的に削除されます。

ダイナミック メンバーシップ ルールは、グループの作成時に membershipRule プロパティを使用して指定されます。 たとえば、「 "membershipRule": 'user.department -eq "Marketing"' 」のように入力します。 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"
}

メンバーシップ ルールの作成の詳細については、「Azure Active Directory のダイナミック メンバーシップ ルール」を参照してください。

注:: ダイナミック メンバーシップ ルールでは、テナントは、1 つ以上のダイナミック グループのメンバーである一意のユーザーごとに、少なくとも Azure AD Premium 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) のリンクに従って取得したグループのプロファイルを読み取ることができます。

グループでゲスト ユーザーが実行できる操作の詳細については、「メンバーとゲストの既定のアクセス許可を比較する」を参照してください。

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

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

一般的なユース ケース

Microsoft Graph を使用して、次の一般的な操作を実行することができます。

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

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

新機能

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