グループを作成する

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

要求本文で指定した新しいグループを作成します。 以下のいずれかのグループを作成できます:

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

この操作は既定で各グループのプロパティのサブセットのみを返します。 これらの既定のプロパティは、「プロパティ」セクションに記載されています。 既定で返されないプロパティを取得するには、GET 操作を実行し、$select OData クエリ オプションでプロパティを指定します。

注:チームを作成するには、まずグループを作成し、それからそのグループにチームを追加します。チームの作成に関するページを参照してください。

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

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

アクセス許可

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

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

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

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

HTTP 要求

POST /groups

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。

要求本文

要求本文で、グループ オブジェクトの 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 サイトが自動的に作成されない可能性があります。

  • 委任されたコンテキストで Microsoft 365 またはセキュリティ グループを作成し、管理者以外のユーザーとしてサインインし、所有者を指定しないと、呼び出し元のユーザーがグループの所有者として自動的に追加されます。 管理者ユーザーは、作成した Microsoft 365 グループのグループ所有者として自動的に追加されますが、セキュリティ グループには追加されません。

  • 管理者以外のユーザーは、自身をグループ所有者コレクションに追加できません。 詳細については、関連する 既知の問題を参照してください。

  • 以下のプロパティは、最初の POST 要求では設定できません。後続の PATCH 要求で設定する必要があります: accessType、 allowExternalSenders、 autoSubscribeNewMembers、 hideFromAddressLists、 hideFromOutlookClients、 isFavorite、 isSubscribedByMail、 unseenConversationsCount、 unseenCount、 unseenMessagesCount、 welcomeMessageEnabled。

グループ リソースは拡張機能をサポートしているため、 リソースの作成時にカスタム プロパティを独自のデータとともにグループに追加することができます。

groupTypes オプション

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

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

応答

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

例

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

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

要求

次の例は要求を示しています。

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

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

応答

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

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

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

{
   "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
     "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
     "deletedDateTime": null,
     "classification": null,
     "createdDateTime": "2018-12-22T02:21:05Z",
     "description": "Self help community for golf",
     "displayName": "Golf Assist",
     "expirationDateTime": null,
     "groupTypes": [
         "Unified"
     ],
   "isAssignableToRole": null,
     "mail": "golfassist@contoso.com",
     "mailEnabled": true,
     "mailNickname": "golfassist",
     "membershipRule": null,
     "membershipRuleProcessingState": null,
     "onPremisesLastSyncDateTime": null,
     "onPremisesSecurityIdentifier": null,
     "onPremisesSyncEnabled": null,
     "preferredDataLocation": "CAN",
     "preferredLanguage": null,
     "proxyAddresses": [
         "SMTP:golfassist@contoso.com"
     ],
     "renewedDateTime": "2018-12-22T02:21:05Z",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": false,
   "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
     "theme": null,
     "visibility": "Public",
     "onPremisesProvisioningErrors": []
}

例 2: 所有者とメンバーを指定してセキュリティ グループを作成する

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

管理者以外のユーザーは、自身をグループ所有者コレクションに追加できません。 詳細については、関連する 既知の問題を参照してください。

要求

次の例は要求を示しています。

POST https://graph.microsoft.com/beta/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/beta/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/beta/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/beta/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

応答

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/1226170d-83d5-49b8-99ab-d1ab3d91333e/Microsoft.DirectoryServices.Group",
    "id": "1226170d-83d5-49b8-99ab-d1ab3d91333e",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:14:44Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "infoCatalogs": [],
    "isAssignableToRole": null,
    "isManagementRestricted": 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:14:44Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-304486157-1236829141-2882644889-1043566909",
    "theme": null,
    "visibility": null,
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

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

要求

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

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

POST https://graph.microsoft.com/beta/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/beta/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/beta/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

応答

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/1afc3ca3-b14d-43af-9c70-8ae3a5065454/Microsoft.DirectoryServices.Group",
    "id": "1afc3ca3-b14d-43af-9c70-8ae3a5065454",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:16:21Z",
    "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@Contoso.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@Contoso.com"
    ],
    "renewedDateTime": "2021-09-21T07:16:21Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-452738211-1135587661-3817500828-1414792869",
    "theme": null,
    "visibility": "Private",
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

関連コンテンツ

  • 最終更新: