グループを作成する

名前空間: microsoft.graph

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

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

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

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

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

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

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

HTTP 要求

POST /groups

要求ヘッダー

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

要求本文

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

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

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

重要

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

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

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

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",
      "creationOptions": [],
      "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",
    "creationOptions": [],
    "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: Azure AD ロールに割り当てることができる Microsoft 365 グループを作成する

要求

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

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 に設定されているグループは、動的メンバーシップの種類にすることはできません。また、所有者を持つこともできません。 詳細については、「グループを使用して Azure AD ロールの割り当てを管理する」を参照してください。

応答

応答の例を次に示します。 既定のプロパティのみが含まれています。 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": []
}