Upsert 组

  • 项目

命名空间：microsoft.graph

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

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

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

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

权限

为此 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 请求

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 的对象已存在，此方法将更新 组 对象并返回 204 No Content 响应代码。

示例

示例 1：Create 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：Create具有所有者和成员的安全组（如果不存在）

以下示例创建具有指定所有者和成员的安全组，因为不存在具有指定 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

相关内容