创建组

  • 项目

命名空间：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
委派（个人 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 门户 创建的组始终将 securityEnabled 最初设置为 true。

重要

  • 使用 Group.Create 应用程序权限创建组而不指定所有者时，将会以匿名方式创建组，并且该组不可修改。 创建组时，将所有者添加到组以指定可以修改该组的所有者。

  • 以编程方式创建 Microsoft 365 组时，若具有仅应用上下文且未指定所有者，则将以匿名方式创建组。 这样会导致在进一步执行手动操作前无法自动创建相关联的 SharePoint Online 网站。

  • 无法在初始 POST 请求中设置以下属性，并且必须在后续 PATCH 请求中设置：allowExternalSenders，autoSubscribeNewMembers， hideFromAddressLists，hideFromOutlookClients， isSubscribedByMail，unseenCount。

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,
    "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: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": []
}