#  用户组资源介绍

用户组是飞书通讯录中基础实体之一，在用户组内可添加用户或部门资源。各类业务权限管控可以与用户组关联，从而实现高效便捷的成员权限管控。

## 使用场景

目前，以下企业管理场景均已支持按用户组进行权限管控：
- 管理员对用户组设置应用可用性
- 管理员对用户组设置工作台推荐应用
- 管理员基于用户组设置组织架构可见范围
- 管理员基于用户组设置个人名片页字段可见性
- 管理员基于用户组设置组织内会话权限
- 管理员对用户组设置文档禁用权限
- 管理员对用户组设置禁止对外沟通
- 管理员基于用户组设置文档权限默认值

例如，你可以通过 OpenAPI 将企业的外包成员维护到“外包用户组”，在应用可用范围或其他业务管控规则中选择该“外包用户组”，即可为企业外包成员统一设定权限范围。这样可节省在各业务权限里手动操作的成本。

## 基本概念

在使用用户组 API 之前，请先了解用户组相关概念。

### 用户组类型

用户组分为普通用户组和动态用户组两类，这两类用户组的主要差异是在用户分组方式上，在普通用户组内需要手动增删用户或部门，而动态用户组则是根据一定的规则或条件自动增删用户或部门。

如需了解更多信息，可参见[普通用户组](https://www.feishu.cn/hc/zh-CN/articles/360049067479)、[动态用户组](https://www.feishu.cn/hc/zh-CN/articles/360049067874)。warning
在使用用户组 API 时，你需要注意不同 API 所支持的用户组类型也不同。说明如下：

- 调用用户组 API 仅支持创建、更新、删除普通用户组，不支持操作动态用户组。
- 调用用户组查询类型 API （包括 **查询指定用户组**、**查询用户组列表**、**查询用户所属用户组**）时，支持查询普通用户组和动态用户组的数据。

### 用户组 ID

用户组 ID `group_id` 用来标识租户内唯一的用户组，该 ID 在创建用户组时支持自定义设置，若不自定义则由系统默认生成。待用户组创建后，用户组 ID 不支持修改。

#### 用户组 ID 设置建议

如果你的企业内部系统已有类似用户组的实体，并且希望同步到飞书用户组实现一些业务权限管控，那么你可以在创建用户组时，将本企业内部系统的 ID 设置为用户组 ID，由此实现飞书用户组 ID 和内部系统 ID 的一致性，节省跨系统调用的映射成本。

#### 用户组 ID 获取方式

你可以通过以下方式获取用户组 ID。

- 方式一：调用接口获取

- [创建用户组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/create)，成功创建会返回用户组 ID。
	- [查询用户组列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/simplelist)，获取用户组 ID。

- 方式二：从管理后台查看

企业管理员可以登录[管理后台](https://feishu.cn/admin/index)，在 **组织架构 > 用户组管理** 页面，点击指定用户组的 **查看用户组详情** 按钮，即可查看用户组 ID。

## 用户组字段说明

名称 | 类型 | 描述
---|---|---
group_id | string | 用户组 ID，是租户内用户组的唯一标识。使用说明：<br>- group_id 可在[创建用户组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/create)时自定义，若不自定义则由系统自动生成。<br>- 已创建的用户组，不允许修改 group_id。<br>- 通过 group_id，你可以调用[查询指定用户组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/get)接口，获取用户组详细信息。<br>- 你可以调用[查询用户组列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/simplelist)，获取当前租户内所有用户组的 ID 及其他配置信息。<br>**自定义`group_id`时，数据校验规则如下：**<br>- 最大长度：`64` 字符<br>- 校验规则：数字、大小写字母的组合，不能包含空格<br>**示例值**："g122817"
name | string | 用户组的名字。租户内唯一。<br>**数据校验规则：** 最大长度为 `100` 字符<br>**示例值**："IT 外包组"
description | string | 用户组描述信息。<br>**数据校验规则：** 最大长度为 `500` 字符<br>**示例值**："IT 外包用户组，需要进行细粒度权限管控"
type | int | 用户组的类型。<br>**可选值有：**<br>- 1：普通用户组。该枚举值在用户组 API 内全局适用。<br>- 2：动态用户组。该枚举值仅在查询类的用户组 API 内适用。查询类 API 包括[查询指定用户组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/get)、[查询用户组列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/simplelist)、[查询用户所属用户组](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/group/member_belong)。

## 数据示例

```json 
{
	"id": "g193821",
	"name": "IT 外包组",
	"description": "IT 外包组，需要对该组人群进行细颗粒度权限管控。",
	"type": 1
}
```