创建组

命名空间：microsoft.graph

创建请求正文中指定的新组。 你可以创建以下类型的组：

  • Microsoft 365 组（统一组）
  • 安全组

此操作在默认情况下仅返回每个组的一部分属性。 这些默认属性将记录在属性部分中。

若要获取非默认返回的属性，请执行 GET 操作，并在 $select OData 查询选项中指定这些属性。

注意：虽然 Microsoft Teams 是在 Microsoft 365 组的基础之上构建而成，但暂不能通过此 API 创建团队。 可以使用其他组 API 来管理已在 Microsoft Teams UI 中创建的团队。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 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}。 必填。 详细了解 身份验证和授权。
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 门户创建的组始终将 securityEnabled 最初设置为 true。

重要

  • 使用 Group.Create 应用程序权限创建组而不指定所有者将匿名创建组，并且无法修改该组。 在创建组时向组添加所有者，以便所有者可以管理该组。

  • 在仅限应用的上下文中创建 Microsoft 365 组且不指定所有者将匿名创建该组。 这样会导致在进一步执行手动操作前无法自动创建相关联的 SharePoint Online 网站。

  • 在委派上下文中创建 Microsoft 365 或安全组，以非管理员用户身份登录且不指定所有者会自动将调用用户添加为组所有者。 系统会自动添加管理员用户为他们创建的 Microsoft 365 组的组所有者，但不属于安全组。

  • 非管理员用户无法将自己添加到组所有者集合。 有关详细信息，请参阅相关的 已知问题。

  • 以下属性不能在初始 POST 请求中设置，必须在后续 PATCH 请求中设置： accessType、 allowExternalSenders、 autoSubscribeNewMembers、 hideFromAddressLists、 hideFromOutlookClients、 isFavorite、 isSubscribedByMail、 unseenConversationsCount、 unseenCount、 unseenMessagesCount。

groupTypes 选项

使用 groupTypes 属性来控制组的类型及其成员身份，如图所示。

组类型 已分配成员身份 动态成员身份
Microsoft 365（也称为统一组） ["Unified"] ["Unified","DynamicMembership"]
动态 [] (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 组

请求

以下示例显示了一个请求。 必须为调用用户分配 RoleManagement.ReadWrite.Directory 权限，才能设置 isAssignableToRole 属性或更新此类组的成员身份。

将 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,
    "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: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": []
}
  • Last updated on