创建组Create group

重要

Microsoft Graph 中/beta的版本下的 api 可能会发生更改。APIs under the /beta version in Microsoft Graph are subject to change. 不支持在生产应用程序中使用这些 API。Use of these APIs in production applications is not supported.

创建请求正文中指定的新Create a new group as specified in the request body. 你可以创建以下组之一:You can create one of the following groups:

  • Office 365 组(统一组)Office 365 group (unified group)
  • 安全组Security group

此操作在默认情况下仅返回每个组的一部分属性。This operation returns by default only a subset of the properties for each group. 这些默认属性将记录在属性部分中。These default properties are noted in the Properties section. 若要获取_非_默认返回的属性,请执行 GET 操作,并在 $select OData 查询选项中指定这些属性。To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.

注意:若要创建团队,首先要创建组,然后向组添加团队,请参阅创建团队Note: To create a team, first create a group then add a team to it, see create team.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) Group.ReadWrite.All、Directory.ReadWrite.All、Directory.AccessAsUser.AllGroup.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 不支持。Not supported.
应用程序Application Group.Create、Group.ReadWrite.All、Directory.ReadWrite.AllGroup.ReadWrite.All, Directory.ReadWrite.All

HTTP 请求HTTP request

POST /groups

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization stringstring Bearer {token}。必需。Bearer {token}. Required.

请求正文Request body

下表显示了创建组时要指定的资源的属性。The following table shows the properties of the group resource to specify when you create a group.

属性Property 类型Type 说明Description
displayNamedisplayName stringstring 要在组的通讯簿中显示的名称。The name to display in the address book for the group. 必需。Required.
mailEnabledmailEnabled 布尔boolean 对于已启用邮件的组,请设置为 trueSet to true for mail-enabled groups. 必需。Required.
mailNicknamemailNickname stringstring 组的邮件别名。The mail alias for the group. 必需。Required.
securityEnabledsecurityEnabled booleanboolean 对于启用安全机制的组(包括 Office 365 组),请设置为 trueSet to true for security-enabled groups, including Office 365 groups. 必需。Required.
ownersowners directoryObject collectiondirectoryObject collection 此属性表示创建时指定的组所有者。This property represents the owners for the group at creation time. 可选。Optional.
membersmembers directoryObject collectiondirectoryObject collection 此属性表示创建时指定的组成员。This property represents the members for the group at creation time. 可选。Optional.

注意: 使用 Microsoft Azure 门户创建的组始终将 securityEnabled 初始设置为 trueNote: Groups created using the Microsoft Azure portal always have securityEnabled initially set to true.

由于资源支持扩展,因此可以使用 POST 操作,并在创建组时向其添加含有自己的数据的自定义属性。Because the group resource supports extensions, you can use the POST operation and add custom properties with your own data to the group while creating it.

注意: 在不指定所有者的情况下使用 Group.Create 应用程序权限创建组时,将会以匿名方式创建组,并且组将不可修改。Note: Creating a group using the Group.Create application permission without specifying owners will create the group anonymously and the group will not be modifiable. 创建组时,可使用 POST 操作并为其添加所有者,以便指定可修改该组的所有者。You can use the POST operation and add owners to the group while creating it to specify owners who can modify the group.

以编程方式创建 Office 365 组时,若具有仅应用上下文且未指定所有者,则将以匿名方式创建组。Note: Creating an Office 365 group programmatically with an app-only context and without specifying owners will create the group anonymously. 这样会导致在进一步执行手动操作前无法自动创建相关联的 SharePoint Online 网站。Doing so can result in the associated SharePoint Online site not being created automatically until further manual action is taken.

根据需要为你的组指定其他可写属性。Specify other writable properties as necessary for your group. 有关详细信息,请参阅资源的属性。For more information, see the properties of the group resource.

groupTypes 选项groupTypes options

使用 groupTypes 属性来控制组的类型及其成员身份,如图所示。Use the groupTypes property to control the type of group and its membership, as shown.

组类型Type of group 已分配成员身份Assigned membership 动态成员身份Dynamic membership
Office 365(也称为统一组)Office 365 (aka unified group) ["Unified"] ["Unified","DynamicMembership"]
动态Dynamic [] (null)[] (null) ["DynamicMembership"]

响应Response

如果成功,此方法会在响应正文中返回 201 Created 响应代码和 group 对象。If successful, this method returns a 201 Created response code and a group object in the response body. 该响应仅包括组的默认属性。The response includes only the default properties of the group.

示例Examples

示例 1:创建 Office 365 组Example 1: Create an Office 365 group

以下示例将创建 Office 365 组。The following example creates an Office 365 group.

请求Request

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

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

响应Response

下面是一个响应示例。The following is an example of the response.

注意: 为了提高可读性,可能缩短了此处显示的响应对象。Note: The response object shown here might be shortened for readability. 在实际调用中会返回所有默认属性。All the default properties are returned from an actual call.

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

{
     "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"
     ],
     "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.onmicrosoft.com"
     ],
     "renewedDateTime": "2018-12-22T02:21:05Z",
     "resourceBehaviorOptions": [],
     "resourceProvisioningOptions": [],
     "securityEnabled": false,
     "theme": null,
     "visibility": "Public",
     "onPremisesProvisioningErrors": []
}

示例 2:创建包含所有者和成员的 Office 365 组Example 2: Create an Office 365 group with an owner and members

以下示例将创建一个具有指定所有者和成员的 Office 365 组。The following example creates an Office 365 group with an owner and members specified.

请求Request

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

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "operations2019",
  "securityEnabled": false,
  "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"
  ]
}

响应Response

下面是成功响应的示例。The following is an example of a successful response. 它仅包括默认属性。It includes only default properties. 随后可获取组的 ownersmembers 导航属性,以验证所有者或成员。You can subsequently get the owners or members navigation properties of the group to verify the owner or members.

注意: 为了提高可读性,可能缩短了此处显示的响应对象。Note: The response object shown here might be shortened for readability. 在实际调用中会返回所有默认属性。All the default properties are returned from an actual call.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "id": "502df398-d59c-469d-944f-34a50e60db3f",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2018-12-27T22:17:07Z",
    "creationOptions": [],
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "groupTypes": [
        "Unified"
    ],
    "mail": "operations2019@contoso.com",
    "mailEnabled": true,
    "mailNickname": "operations2019",
    "onPremisesLastSyncDateTime": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "CAN",
    "proxyAddresses": [
        "SMTP:operations2019@contoso.com"
    ],
    "renewedDateTime": "2018-12-27T22:17:07Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "visibility": "Public",
    "onPremisesProvisioningErrors": []
}

另请参阅See also