グループを作成する

  • [アーティクル]

名前空間: microsoft.graph

要求本文で指定した新しいグループを作成します。 次に示す種類のグループを作成できます。

  • Microsoft 365 グループ (統合グループ)
  • セキュリティ グループ

この操作は既定で各グループのプロパティのサブセットのみを返します。 これらの既定のプロパティは、「プロパティ」セクションに記載されています。

既定で返されないプロパティを取得するには、GET 操作を実行し、$select OData クエリ オプションでプロパティを指定します。

注: Microsoft Teams は Microsoft 365 グループで構築されていますが、この API を使用してチームを作成することは現在できません。 Microsoft Teams UI で作成されたチームの管理に、その他のグループ API を使用することができます。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) Group.ReadWrite.All Directory.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション Group.Create Directory.ReadWrite.All、Group.ReadWrite.All

Group.Create アクセス許可がある間に所有者またはメンバーを含むグループを作成するアプリの場合、アプリには、グループ所有者またはメンバーとして割り当てるオブジェクトの種類を読み取る権限が必要です。 そこで：

  • アプリは、グループの所有者またはメンバーとして自身を割り当てることができます。
  • 所有者またはメンバーとしてユーザーを含むグループを作成するには、アプリに少なくとも User.Read.All アクセス許可が必要です。
  • 所有者またはメンバーとして他のサービス プリンシパルを使用してグループを作成するには、アプリに 少なくとも Application.Read.All アクセス許可が必要です。
  • ユーザーまたはサービス プリンシパルを所有者またはメンバーとしてグループを作成するには、アプリに少なくとも Directory.Read.All アクセス許可が必要です。

HTTP 要求

POST /groups

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。
Content-Type application/json

要求本文

要求本文で、グループ オブジェクトの JSON 表記を指定します。

次の表に、 グループを作成するときに必要なプロパティを示します。 グループの必要に応じて他の書き込み可能なプロパティを指定します。

プロパティ 種類 説明
displayName String アドレス帳に表示するグループの名前。 最大長: 256 文字 必須です。
mailEnabled Boolean メールが有効なグループの場合は、true に設定します。 必須です。
mailNickname String 組織内の Microsoft 365 グループに対して一意の、グループのメール エイリアス。 最大文字数は 64 文字です。 このプロパティには、 ASCII 文字セット 0 ~ 127 の文字のみを含めることができます。ただし、以下の @ () \ [] " ; : <> , SPACEを除いたものです。 必須です。
securityEnabled Boolean Microsoft 365 グループを含む、セキュリティが有効なグループに true を設定します。 必須です。 メモ：Microsoft Entra管理センターまたはAzure portalを使用して作成されたグループには、常に securityEnabled が最初に にtrue設定されています。

重要

  • Group.Create アプリケーションのアクセス許可を使用して所有者を指定せずにグループを作成すると、グループが匿名で作成され、そのグループは変更できなくなります。 グループを変更できる所有者を指定するには、グループの作成中に所有者をグループに追加します。

  • 所有者を指定しないで、アプリ専用コンテキストを用いたプログラムに従って Microsoft 365 グループを作成すると、グループは匿名で作成されます。 この操作を行うと、さらに手動操作が行われるまで、関連付けられている SharePoint Online サイトが自動的に作成されない可能性があります。

  • 以下のプロパティは、最初の POST 要求では設定できないため、後続の PATCH 要求で設定する必要があります。allowExternalSenders、autoSubscribeNewMembers、hideFromAddressLists、hideFromOutlookClients、isSubscribedByMail、unseenCount。

groupTypes オプション

示すように、groupTypes プロパティを使用し、グループの種類とグループのメンバーシップを管理します:

グループの種類 割り当て済みのメンバーシップ 動的メンバーシップ
Microsoft 365 (統合グループ) ["Unified"] ["Unified","DynamicMembership"]
Dynamic [] (null) ["DynamicMembership"]

応答

成功した場合、このメソッドは 201 Created 応答コードと、応答本文で group オブジェクトを返します。 応答には、そのグループの既定のプロパティのみが含まれます。

例

例 1: Microsoft 365 グループを作成する

次の例では Microsoft 365 グループを作成します。 所有者が指定されていないため、呼び出し元ユーザーはグループの所有者として自動的に追加されます。

要求

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
  "description": "Self help community for library",
  "displayName": "Library Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "library",
  "securityEnabled": false
}

応答

次の例は応答を示しています。 preferredDataLocation プロパティの値は、グループ作成者の優先されるデータの場所から継承されます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "b320ee12-b1cd-4cca-b648-a437be61c5cd",
      "deletedDateTime": null,
      "classification": null,
      "createdDateTime": "2018-12-22T00:51:37Z",
      "description": "Self help community for library",
      "displayName": "Library Assist",
      "groupTypes": [
          "Unified"
      ],
      "mail": "library7423@contoso.com",
      "mailEnabled": true,
      "mailNickname": "library",
      "onPremisesLastSyncDateTime": null,
      "onPremisesSecurityIdentifier": null,
      "onPremisesSyncEnabled": null,
      "preferredDataLocation": "CAN",
      "proxyAddresses": [
          "SMTP:library7423@contoso.com"
      ],
      "renewedDateTime": "2018-12-22T00:51:37Z",
      "resourceBehaviorOptions": [],
      "resourceProvisioningOptions": [],
      "securityEnabled": false,
      "visibility": "Public",
      "onPremisesProvisioningErrors": []
}

例 2: 所有者とメンバーを指定してグループを作成する

次の例では、所有者とメンバーを指定してセキュリティ グループを作成します。 グループ作成の一部として、所有者やメンバーなどの最大 20 個の関係を追加できます。 その後、メンバーの追加 API または JSON バッチ処理を使用して、さらにメンバーを追加できます。

要求

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
  ],
  "mailEnabled": false,
  "mailNickname": "operations2019",
  "securityEnabled": true,
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

応答

成功応答の例を次に示します。 既定のプロパティのみが含まれています。 その後は、グループの owners ナビゲーション プロパティまたは members ナビゲーション プロパティを取得して所有者またはメンバーの詳細を確認できます。 preferredDataLocation プロパティの値は、グループ作成者の優先されるデータの場所から継承されます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/21d05557-b7b6-418f-86fa-a3118d751be4/Microsoft.DirectoryServices.Group",
    "id": "21d05557-b7b6-418f-86fa-a3118d751be4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:09:14Z",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "isAssignableToRole": null,
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "operations2019",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [],
    "renewedDateTime": "2021-09-21T07:09:14Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-567301463-1099937718-295959174-3827004813",
    "theme": null,
    "visibility": null,
    "onPremisesProvisioningErrors": []
}

例 3: Microsoft Entra ロールに割り当てることができる Microsoft 365 グループを作成する

要求

次の例は要求を示しています。 isAssignableToRole プロパティを設定したり、そのようなグループのメンバーシップを更新したりするには、呼び出し元のユーザーに RoleManagement.ReadWrite.Directory アクセス許可を割り当てる必要があります。

isAssignableToRole プロパティが にtrue設定されているグループは、動的メンバーシップの種類にすることはできません。securityEnabled は にtrue設定する必要があり、可視性は にのみ設定Privateできます。

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": true,
    "mailEnabled": true,
    "securityEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

注:isAssignableToRole プロパティが true に設定されているグループは、動的メンバーシップの種類にすることはできません。また、所有者を持つこともできません。 詳細については、「グループを使用したMicrosoft Entraロールの割り当ての管理」を参照してください。

応答

次の例は応答を示しています。 既定のプロパティのみが含まれています。 preferredDataLocation プロパティの値は、グループ作成者の優先されるデータの場所から継承されます。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/55ea2e8c-757f-4f2d-be9e-53c22e8c6a54/Microsoft.DirectoryServices.Group",
    "id": "55ea2e8c-757f-4f2d-be9e-53c22e8c6a54",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:23:06Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "infoCatalogs": [],
    "isAssignableToRole": true,
    "isManagementRestricted": null,
    "mail": "contosohelpdeskadministrators@M365x010717.onmicrosoft.com",
    "mailEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "EU",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:contosohelpdeskadministrators@M365x010717.onmicrosoft.com"
    ],
    "renewedDateTime": "2021-09-21T07:23:06Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-1441410700-1328379263-3260260030-1416268846",
    "theme": null,
    "visibility": "Private",
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}