跳转至

employees

feishu.directory.employees

EmployeesNamespace

Bases: Namespace

飞书人事 Directory 员工接口。

通过 client.directory.employees 访问。与通讯录 client.contact.users 不同，本命名空间 调用 directory/v1 员工实体，可按需拉取自定义字段；SDK 不解释字段含义，也不按邮箱过滤。

飞书文档

批量获取员工信息

源代码位于： feishu/directory/employees.py
Python
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class EmployeesNamespace(Namespace):
    r"""
    飞书人事 Directory 员工接口。

    通过 `client.directory.employees` 访问。与通讯录 `client.contact.users` 不同，本命名空间
    调用 `directory/v1` 员工实体，可按需拉取自定义字段；SDK 不解释字段含义，也不按邮箱过滤。

    飞书文档:
        [批量获取员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/employee/mget)
    """

    async def mget(
        self,
        employee_ids: Iterable[str],
        *,
        required_fields: Iterable[str],
        employee_id_type: str | None = None,
        department_id_type: str | None = None,
    ) -> NestedDict:
        r"""
        按员工 ID 批量获取员工详情。

        `employee_ids` 的解释方式由 `employee_id_type` 决定。飞书限制单次最多 100 个 ID；
        超过时直接抛出 [ValueError][]。`required_fields` 原样发给飞书，例如
        `base_info.employee_id`、`base_info.custom_field_values`。

        Args:
            employee_ids: 员工 ID 列表，单次最多 100 个。
            required_fields: 需要返回的字段路径列表。
            employee_id_type: 员工 ID 类型，如 `open_id`、`user_id`、`employee_id`；为空时省略。
            department_id_type: 部门 ID 类型；为空时省略。

        Returns:
            飞书返回的 `data` 数据体，通常含 `employees` 与 `abnormals`。

        Raises:
            ValueError: 当传入的员工 ID 超过 100 个时抛出。
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [批量获取员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/employee/mget)
        """
        ids = list(employee_ids)
        if len(ids) > _MAX_EMPLOYEE_IDS:
            raise ValueError(f"mget accepts at most {_MAX_EMPLOYEE_IDS} employee_ids per call, got {len(ids)}")
        params: dict[str, Any] = {}
        if employee_id_type is not None:
            params["employee_id_type"] = employee_id_type
        if department_id_type is not None:
            params["department_id_type"] = department_id_type
        body = {
            "employee_ids": ids,
            "required_fields": list(required_fields),
        }
        return await self._request_data(
            "POST",
            "directory/v1/employees/mget",
            params=params or None,
            json=body,
        )

mget async

Python
mget(employee_ids: Iterable[str], *, required_fields: Iterable[str], employee_id_type: str | None = None, department_id_type: str | None = None) -> NestedDict

按员工 ID 批量获取员工详情。

employee_ids 的解释方式由 employee_id_type 决定。飞书限制单次最多 100 个 ID； 超过时直接抛出 ValueError。required_fields 原样发给飞书，例如 base_info.employee_id、base_info.custom_field_values。

参数：

名称 类型 描述 默认
employee_ids
Iterable[str]

员工 ID 列表，单次最多 100 个。

 必需
required_fields
Iterable[str]

需要返回的字段路径列表。

 必需
employee_id_type
str | None

员工 ID 类型，如 open_id、user_id、employee_id；为空时省略。

 None
department_id_type
str | None

部门 ID 类型；为空时省略。

 None

返回：

类型 描述
NestedDict

飞书返回的 data 数据体，通常含 employees 与 abnormals。

引发：

类型 描述
ValueError

当传入的员工 ID 超过 100 个时抛出。
FeishuError

请求失败或返回错误码时抛出。
飞书文档

批量获取员工信息

源代码位于： feishu/directory/employees.py
Python
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
async def mget(
    self,
    employee_ids: Iterable[str],
    *,
    required_fields: Iterable[str],
    employee_id_type: str | None = None,
    department_id_type: str | None = None,
) -> NestedDict:
    r"""
    按员工 ID 批量获取员工详情。

    `employee_ids` 的解释方式由 `employee_id_type` 决定。飞书限制单次最多 100 个 ID；
    超过时直接抛出 [ValueError][]。`required_fields` 原样发给飞书，例如
    `base_info.employee_id`、`base_info.custom_field_values`。

    Args:
        employee_ids: 员工 ID 列表，单次最多 100 个。
        required_fields: 需要返回的字段路径列表。
        employee_id_type: 员工 ID 类型，如 `open_id`、`user_id`、`employee_id`；为空时省略。
        department_id_type: 部门 ID 类型；为空时省略。

    Returns:
        飞书返回的 `data` 数据体，通常含 `employees` 与 `abnormals`。

    Raises:
        ValueError: 当传入的员工 ID 超过 100 个时抛出。
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [批量获取员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/employee/mget)
    """
    ids = list(employee_ids)
    if len(ids) > _MAX_EMPLOYEE_IDS:
        raise ValueError(f"mget accepts at most {_MAX_EMPLOYEE_IDS} employee_ids per call, got {len(ids)}")
    params: dict[str, Any] = {}
    if employee_id_type is not None:
        params["employee_id_type"] = employee_id_type
    if department_id_type is not None:
        params["department_id_type"] = department_id_type
    body = {
        "employee_ids": ids,
        "required_fields": list(required_fields),
    }
    return await self._request_data(
        "POST",
        "directory/v1/employees/mget",
        params=params or None,
        json=body,
    )