跳转至

tables

feishu.bitable.tables

TablesNamespace

Bases: Namespace

多维表格数据表（table）接口命名空间。

通过 client.bitable.tables 访问，封装数据表相关的服务端接口，包括数据表的列举、创建与删除。 数据表归属于某个多维表格应用，常以 table_id 标识。

通常无需直接实例化，应通过 client.bitable.tables 访问。

飞书文档

列出数据表

源代码位于： feishu/bitable/tables.py
Python
 32
 33
 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
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
class TablesNamespace(Namespace):
    r"""
    多维表格数据表（table）接口命名空间。

    通过 `client.bitable.tables` 访问，封装数据表相关的服务端接口，包括数据表的列举、创建与删除。
    数据表归属于某个多维表格应用，常以 `table_id` 标识。

    通常无需直接实例化，应通过 `client.bitable.tables` 访问。

    飞书文档:
        [列出数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/list)
    """

    async def create(self, app_token: str, table: dict[str, Any]) -> NestedDict:
        r"""
        新增一张数据表。

        `table` 是描述待创建数据表的请求体，原样作为 `table` 字段并入请求体，常见键包括
        `name`、`default_view_name`、`fields` 等。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table: 数据表定义对象，例如 `{"name": "新表", "fields": [...]}`。

        Returns:
            创建结果数据，含新建数据表的 `table_id`，以及（视请求而定）`default_view_id`、
            `field_id_list` 等字段。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [新增数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/create)

        Examples:
            >>> await client.bitable.tables.create("bascnxxx", {"name": "Tasks"})  # doctest:+SKIP
            {'table_id': 'tblcnnew', 'default_view_id': 'vewxxx', ...}  # noqa: E501
        """
        return await self._request_data(
            "POST", f"bitable/v1/apps/{quote_segment(app_token)}/tables", json={"table": table}
        )

    async def delete(self, app_token: str, table_id: str) -> NestedDict:
        r"""
        删除一张数据表。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 待删除数据表的 `table_id`。

        Returns:
            接口返回的数据（通常为空）。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [删除数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/delete)

        Examples:
            >>> await client.bitable.tables.delete("bascnxxx", "tblcn1")  # doctest:+SKIP
            {}
        """
        return await self._request_data(
            "DELETE", f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}"
        )

    async def list(self, app_token: str, *, page_size: int = 50, max_items: int | None = None) -> list[NestedDict]:
        r"""
        列出多维表格下的数据表。

        自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
        [feishu.consts.MAX_PAGE_SIZE][] 以内。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            page_size: 每页条数，默认为 50，超过上限时按上限截断。
            max_items: 最多返回的条数；为空表示返回全部。

        Returns:
            数据表数据列表，每项包含 `table_id`、`name`、`revision` 等字段。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [列出数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/list)

        Examples:
            >>> await client.bitable.tables.list("bascnxxx")  # doctest:+SKIP
            [{'table_id': 'tblcn1', 'name': 'Sheet1', ...}, {'table_id': 'tblcn2', ...}]  # noqa: E501
        """
        return await self._client.paginate_get(
            f"bitable/v1/apps/{quote_segment(app_token)}/tables",
            page_size=page_size,
            max_items=max_items,
        )

create async

Python
create(app_token: str, table: dict[str, Any]) -> NestedDict

新增一张数据表。

table 是描述待创建数据表的请求体，原样作为 table 字段并入请求体，常见键包括 name、default_view_name、fields 等。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table
dict[str, Any]

数据表定义对象，例如 {"name": "新表", "fields": [...]}。

 必需

返回：

类型 描述
NestedDict

创建结果数据，含新建数据表的 table_id，以及（视请求而定）default_view_id、
NestedDict

field_id_list 等字段。

引发：

类型 描述
FeishuError

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

新增数据表

示例：

Python Console Session
1
2
>>> await client.bitable.tables.create("bascnxxx", {"name": "Tasks"})
{'table_id': 'tblcnnew', 'default_view_id': 'vewxxx', ...}  # noqa: E501
源代码位于： feishu/bitable/tables.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
async def create(self, app_token: str, table: dict[str, Any]) -> NestedDict:
    r"""
    新增一张数据表。

    `table` 是描述待创建数据表的请求体，原样作为 `table` 字段并入请求体，常见键包括
    `name`、`default_view_name`、`fields` 等。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table: 数据表定义对象，例如 `{"name": "新表", "fields": [...]}`。

    Returns:
        创建结果数据，含新建数据表的 `table_id`，以及（视请求而定）`default_view_id`、
        `field_id_list` 等字段。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [新增数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/create)

    Examples:
        >>> await client.bitable.tables.create("bascnxxx", {"name": "Tasks"})  # doctest:+SKIP
        {'table_id': 'tblcnnew', 'default_view_id': 'vewxxx', ...}  # noqa: E501
    """
    return await self._request_data(
        "POST", f"bitable/v1/apps/{quote_segment(app_token)}/tables", json={"table": table}
    )

delete async

Python
delete(app_token: str, table_id: str) -> NestedDict

删除一张数据表。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

待删除数据表的 table_id。

 必需

返回：

类型 描述
NestedDict

接口返回的数据（通常为空）。

引发：

类型 描述
FeishuError

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

删除数据表

示例：

Python Console Session
1
2
>>> await client.bitable.tables.delete("bascnxxx", "tblcn1")
{}
源代码位于： feishu/bitable/tables.py
Python
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
async def delete(self, app_token: str, table_id: str) -> NestedDict:
    r"""
    删除一张数据表。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 待删除数据表的 `table_id`。

    Returns:
        接口返回的数据（通常为空）。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [删除数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/delete)

    Examples:
        >>> await client.bitable.tables.delete("bascnxxx", "tblcn1")  # doctest:+SKIP
        {}
    """
    return await self._request_data(
        "DELETE", f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}"
    )

list async

Python
list(app_token: str, *, page_size: int = 50, max_items: int | None = None) -> list[NestedDict]

列出多维表格下的数据表。

自动翻页并将各页结果拼接为单个列表返回。page_size 会被限制在 [feishu.consts.MAX_PAGE_SIZE][] 以内。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
page_size
int

每页条数，默认为 50，超过上限时按上限截断。

 50
max_items
int | None

最多返回的条数；为空表示返回全部。

 None

返回：

类型 描述
list[NestedDict]

数据表数据列表，每项包含 table_id、name、revision 等字段。

引发：

类型 描述
FeishuError

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

列出数据表

示例：

Python Console Session
1
2
>>> await client.bitable.tables.list("bascnxxx")
[{'table_id': 'tblcn1', 'name': 'Sheet1', ...}, {'table_id': 'tblcn2', ...}]  # noqa: E501
源代码位于： feishu/bitable/tables.py
Python
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
async def list(self, app_token: str, *, page_size: int = 50, max_items: int | None = None) -> list[NestedDict]:
    r"""
    列出多维表格下的数据表。

    自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
    [feishu.consts.MAX_PAGE_SIZE][] 以内。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        page_size: 每页条数，默认为 50，超过上限时按上限截断。
        max_items: 最多返回的条数；为空表示返回全部。

    Returns:
        数据表数据列表，每项包含 `table_id`、`name`、`revision` 等字段。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [列出数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/list)

    Examples:
        >>> await client.bitable.tables.list("bascnxxx")  # doctest:+SKIP
        [{'table_id': 'tblcn1', 'name': 'Sheet1', ...}, {'table_id': 'tblcn2', ...}]  # noqa: E501
    """
    return await self._client.paginate_get(
        f"bitable/v1/apps/{quote_segment(app_token)}/tables",
        page_size=page_size,
        max_items=max_items,
    )