通过

创建组

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

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

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

此操作在默认情况下仅返回每个组的一部分属性。 这些默认属性将记录在属性部分中。 若要获取非默认返回的属性，请执行 GET 操作，并在 $select OData 查询选项中指定这些属性。

注意：若要创建团队，首先要创建组，然后向组添加团队，请参阅创建团队。

此 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}。 必填。 详细了解 身份验证和授权。

请求正文

在请求正文中，提供组对象的 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 请求中设置：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/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：创建包含所有者和成员的安全组

以下示例将创建一个具有指定所有者和成员的 Microsoft 365 组。 请注意，最多可以在组创建中添加 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"
  ]
}

响应

下面是成功响应的示例。 它仅包括默认属性。 随后可获取组的 owners 或 members 导航属性，以验证所有者或成员。 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 组

请求

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

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

相关内容