通过

Upsert 组

  • 项目

命名空间：microsoft.graph

创建新的 组 对象（如果不存在），或更新现有 组 对象的属性。 可以创建或更新以下类型的组：

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

默认情况下，此操作仅返回每个组的属性子集。 有关默认返回的属性列表，请参阅组资源的“属性”部分。 若要获取非默认返回的属性，请执行 GET 操作，并在 $select OData 查询选项中指定这些属性。

注意：若要创建 团队，请先创建一个组，然后向其添加团队。 有关详细信息，请参阅 创建团队。

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Group.ReadWrite.All Directory.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 Group.ReadWrite.All Directory.ReadWrite.All

若要让具有 Group.Create 权限的应用创建包含所有者或成员的组，它必须具有读取要分配为组所有者或成员的对象类型的权限。 因此：

  • 应用可以将自己分配为组的所有者或成员。
  • 若要创建将用户作为所有者或成员的组，应用必须至少具有 User.Read.All 权限。
  • 若要使用其他服务主体作为所有者或成员创建组，应用必须至少具有 Application.Read.All 权限。
  • 若要创建将用户或服务主体作为所有者或成员的组，应用必须至少具有 Directory.Read.All 权限。

HTTP 请求

PATCH /groups/(uniqueName='uniqueName')

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json. 必需。
Prefer create-if-missing. 对于 upsert 行为是必需的，否则请求被视为更新操作。

请求正文

在请求正文中，提供组对象的 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"]

响应

如果 不存在具有 uniqueName 的对象，此方法在 201 Created 响应正文中返回响应代码和新的 组 对象。

如果 不存在具有 uniqueName 的对象， Prefer: create-if-missing 并且 未 指定标头，则此方法将 404 Not Found 返回错误代码。

如果已存在具有 uniqueName 的对象，此方法将更新 组 对象并返回 204 No Content 响应代码。

示例

示例 1：创建Microsoft 365 组（如果不存在）

以下示例创建一个 Microsoft 365 组，因为不存在具有指定 uniqueName 值的组。 由于尚未指定所有者，调用用户将自动添加为组的所有者。

请求

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-type: application/json
Prefer: create-if-missing

{
  "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/v1.0/$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.onmicrosoft.com"
    ],
    "renewedDateTime": "2018-12-22T02:21:05Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
    "theme": null,
    "visibility": "Public",
    "uniqueName": "uniqueName",
    "onPremisesProvisioningErrors": []
}

示例 2：创建包含所有者和成员的安全组（如果不存在）

以下示例创建具有指定所有者和成员的安全组，因为不存在具有指定 uniqueName 值的组。 请注意，最多可以在组创建中添加 20 个关系，如所有者和成员。 随后，可以使用添加成员 API 或 JSON 批处理 添加 多个其他成员。

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

请求

以下示例显示了一个请求。

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
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/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,
    "uniqueName": "uniqueName",
    "visibility": null,
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

示例 3：更新现有组

在此示例中，指定的组已存在，因此操作被视为更新。

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

请求

以下示例显示了一个请求。

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

响应

以下示例显示了相应的响应。 preferredDataLocation 属性的值继承自组创建者的首选数据位置。

HTTP/1.1 204 No Content

相关内容