更新组

命名空间：microsoft.graph

更新 组 对象的属性。

注意

当你用于 members@odata.bind 通过 PATCH添加成员时，此请求可能会对最近创建的组产生复制延迟。 组对象可能需要一小段时间才能跨 Microsoft Entra ID 目录副本完全复制。 在此时段内，请求向组中添加成员可能会返回错误 400 Bad Request ，并显示消息：“ 源资源对象或引用的对象之一不存在。”

要缓解此行为：

  • 短暂延迟后重试 - 等待几秒钟，然后重试请求。 延迟通常是短暂的。

有关详细信息，请参阅 设计 Microsoft Entra 的最终一致性。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

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

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

特定场景的权限

  • Group-NestingSupport.ReadWrite.All 是更新 disableNesting 属性的最小特权权限。

  • Group.ManageProtection.All 委托权限是用于更新云安全组的 assignedLabels 属性的最小特权权限。 不支持仅应用方案。

HTTP 请求

PATCH /groups/{id}

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

在请求正文中，仅提供应更新的属性的值。 请求正文中不包括的现有属性将保留其以前的值，或根据对其他属性值的更改重新计算。

下表指定可更新的属性。

属性 类型 说明
allowExternalSenders Boolean 默认值为“false”。 指示组织外部人员是否可以向该组发送邮件。
assignedLabels assignedLabel 集合 标签 ID (标签名称) 与 Microsoft 365 组或云安全组关联的敏感度标签对的列表。 需要 Microsoft Entra ID P1 许可证。 可以在组创建或更新期间指定此属性。 但是，对于云安全组，它一旦设置就不可变。
  • 对于 Microsoft 365 组，只有在调用方需要 Microsoft Graph 权限和 受支持的管理员角色的委派方案中才能更新此属性。
  • Group.ManageProtection.All 委托的权限是更新云安全组的此属性的最小特权权限。 不支持仅应用方案。
  • 请参阅与 Microsoft 365 组标签的主要差异 ，了解有关管理 Microsoft 365 与云安全组的此属性的详细信息。
autoSubscribeNewMembers Boolean 默认值为“false”。 指示添加到组中的新成员是否将自动订阅接收电子邮件通知。 当组上的subscriptionEnabled设置为 false 时，autoSubscribeNewMembers不能为 true。
说明 String 可选的组说明。
displayName String 组的显示名称。 此属性是在创建组时所必需的，并且在更新过程中不能清除。
mailNickname String 组的邮件别名，它对于组织中的 Microsoft 365 组是唯一的。 最大长度为 64 个字符。 此属性只能包含ASCII 字符集 0 - 127 中的字符，以下除外： @ () \ [] " ; : . <> , SPACE。
preferredDataLocation String Microsoft 365 组的首选数据位置。 若要更新此属性，必须至少为调用用户分配以下 Microsoft Entra 角色之一：
  • 用户帐户管理员
  • 目录写入程序
  • Exchange 管理员
  • SharePoint 管理员

有关此属性详细信息，请参阅 OneDrive Online 多地理位置。
securityEnabled 布尔 指定是否为安全组。
唯一名称 String 可分配给组并用作备用键的唯一标识符。 仅当设置 null 后才能更新，并且一旦设置就不可变。
visibility String 指定 Microsoft 365 组的可见性。 可能的是包括：专用、公用或为空（解释为公用）。

重要

  • 若要更新 accessType、allowExternalSenders、autoSubscribeNewMembers、hideFromAddressLists、hideFromOutlookClients、isFavorite、isSubscribedByMail、unseenConversationsCount、unseenCount、unseeenMessagesCount () 的这些属性，必须：
    • 在其自己的 PATCH 请求中指定它们，而不包括上表中的其他属性
    • 具有 Group.ReadWrite.All 权限 (这些属性不支持 Directory.ReadWrite.All)
  • 只有与核心组管理相关的组 API 子集支持应用程序和委托的权限。 组 API 的所有其他成员（包括更新 autoSubscribeNewMembers）仅支持委派的权限。
  • 在 Microsoft Exchange Server 中更新启用邮件的安全组的规则可能很复杂；若要了解详细信息，请参阅在 Exchange Server 中管理启用邮件的安全组。
  • 更新 assignedLabels 时不支持应用程序权限。 Group.ManageProtection.All 是更新云安全组的 assignedLabels 的最小特权权限。

管理扩展和关联的数据

使用此 API 管理组的 目录、架构和开放扩展 及其数据，如下所示：

  • 在现有组的扩展中添加、更新和存储数据。
  • 对于目录和架构扩展，可通过将自定义扩展属性的值设置为 null 来删除任何存储的数据。 对于开放扩展，请使用 删除开放扩展 API。

响应

如果成功，此方法将返回响应204 No Content代码 - 更新以下属性时的响应代码除外200 OK：accessType、allowExternalSenders、autoSubscribeNewMembers、hideFromAddressLists、hideFromOutlookClients、isFavorite、isSubscribedByMail、unseenConversationsCount、unseenCount、unseenMessagesCount。

错误

状态代码 错误代码 错误消息 说明
400 Bad Request Request_BadRequest “源资源对象或引用的对象之一不存在。” 该组是最近创建的，尚未在所有目录副本中完全复制。 此错误特定于通过) 添加 members@odata.bind 成员 (的链接写入操作。 在短暂延迟后重试请求。

示例

以下示例演示如何更新组。

请求

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

PATCH https://graph.microsoft.com/v1.0/groups/0d09007d-45b2-458c-b180-880dde3a302e
Content-type: application/json

{
  "description": "Library Assist - ADC",
  "displayName": "Library Assist - ADC",
  "mailNickname": "library-help-adc"
}

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content
  • Last updated on