更新用户组

调用该接口更新指定用户组的名称或描述。

注意事项

• 应用的通讯录权限范围需要符合以下任一设置，才可以成功调用本接口。了解应用通讯录权限范围，可参见权限范围资源介绍。

  • 通讯录权限范围设置为 全部员工。
  • 由企业管理员在管理后台设置应用可见范围内包含当前待更新的用户组，然后应用的通讯录权限范围设置为 与应用的可用范围一致。

• API 方式暂不支持更新动态用户组。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/group/:group_id
HTTP Method	PATCH
接口频率限制	100 次/分钟
支持的应用类型	custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	contact:group 更新用户组信息
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
group_id	string	用户组 ID。 用户组 ID 可在创建用户组时从返回值中获取，你也可以调用查询用户组列表接口，获取用户组的 ID。 示例值："g187131"

查询参数

名称	类型	必填	描述
user_id_type	string	否	用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ 默认值：open_id 当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_type	string	否	此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。 示例值：open_department_id 可选值有： - department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。

请求体

名称	类型	必填	描述
name	string	否	用户组名字，长度不能超过 100 字符。 说明：用户组名称企业内唯一，如重复设置则会创建失败。 默认值：空，表示不更新用户组名字。 示例值："外包 IT 用户组"
description	string	否	用户组描述，长度不能超过 500 字符。 默认值：空，表示不更新用户组描述。 示例值："IT 外包用户组，需要进行细粒度权限管控"

请求体示例

{
    "name": "外包 IT 用户组",
    "description": "IT 外包用户组，需要进行细粒度权限管控"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {}
}

错误码

HTTP状态码	错误码	描述	排查建议
500	40003	internal error	内部错误，你可以获取请求的 X-Request-Id，并联系技术支持。
400	42002	invalid group_id	用户组 ID 无效。请检查传入的用户组 ID 是否正确，你可以调用查询用户组列表接口，获取用户组的 ID。
400	42013	group name exceed limit	用户组名字长度超过最大限制。请求时 name 参数取值的长度不能超过 100 字符。
400	42014	group description exceed limit	用户组描述长度超过最大限制。请求时 description 取值的长度不能超过 500 字符。
403	42009	no userGroup authority error	缺少用户组权限。应用的通讯录权限范围需要符合以下任一设置，才可以成功调用本接口。 - 通讯录权限范围设置为 全部员工。 - 由企业管理员在管理后台设置应用可见范围内包含当前待更新的用户组，然后应用的通讯录权限范围设置为 与应用的可用范围一致。 了解应用通讯录权限范围，可参见权限范围资源介绍。
400	42015	user group disable	用户组功能未开启。请联系技术支持处理。
400	47009	duplicated name error	用户组名称重复。用户组名称在企业内唯一，你可以尝试更换其他名称后重试。
400	40001	parameter invalid	参数错误。请检查输入参数是否设置有误，你可以参考接口文档内的参数描述，修复输入参数值。
400	42018	exist invalid dynamic group rule	存在非法的动态用户组规则，请检查请求参数后重试
400	42019	exist invalid dynamic group rule expression	动态用户组匹配规则错误
400	42020	exist unsupported dynamic group rule expression field	动态用户组的匹配规则表达式中传入了不支持的成员属性
400	42021	exist unsupported dynamic group operation	动态用户组的匹配规则表达式中传入了不支持的关系操作指令
400	42022	exist invalid expression value or values	动态用户组的匹配规则表达式中传入了错误、不支持的值，或者传入的单值、多值与关系操作符不匹配
400	42024	no permission to create a dynamic group	没有创建动态用户组的权限，请确认后重试
400	42025	invalid joiner rule	非法的连接规则，请修改后重试
400	42026	department scope exceed limit	部门范围超过限制，请确认后重试

更多错误码信息，参见通用错误码。