跳转至

records

feishu.bitable.records

RecordsNamespace

Bases: Namespace

多维表格记录（record）接口命名空间。

通过 client.bitable.records 访问，封装记录相关的服务端接口，包括记录的查询、检索、创建、更新与 删除，以及对应的批量操作。记录承载数据表中的数据，归属于某张数据表，常以 record_id 标识。

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

飞书文档

记录概述

源代码位于： feishu/bitable/records.py
Python
 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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
class RecordsNamespace(Namespace):
    r"""
    多维表格记录（record）接口命名空间。

    通过 `client.bitable.records` 访问，封装记录相关的服务端接口，包括记录的查询、检索、创建、更新与
    删除，以及对应的批量操作。记录承载数据表中的数据，归属于某张数据表，常以 `record_id` 标识。

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

    飞书文档:
        [记录概述](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/bitable-record-overview)
    """

    async def batch_create(self, app_token: str, table_id: str, records: builtins.list[dict[str, Any]]) -> NestedDict:
        r"""
        批量新增记录。

        `records` 为待新增记录的列表，原样作为 `records` 字段并入请求体，每个元素形如
        `{"fields": {...}}`。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            records: 待新增记录列表，每个元素形如 `{"fields": {"Title": "hi"}}`。

        Returns:
            批量新增结果数据，含新建的 `records` 列表（每项含 `record_id`、`fields`）。

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

        飞书文档:
            [新增多条记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/batch_create)

        Examples:
            >>> recs = [{"fields": {"Title": "a"}}, {"fields": {"Title": "b"}}]
            >>> await client.bitable.records.batch_create("bascnxxx", "tblcn1", recs)  # doctest:+SKIP
            {'records': [{'record_id': 'rec1', ...}, {'record_id': 'rec2', ...}]}  # noqa: E501
        """
        return await self._request_data(
            "POST",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/batch_create",
            json={"records": records},
        )

    async def batch_delete(self, app_token: str, table_id: str, record_ids: builtins.list[str]) -> NestedDict:
        r"""
        批量删除记录。

        `record_ids` 为待删除记录的 ID 列表，原样作为 `records` 字段并入请求体。

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

        Returns:
            批量删除结果数据，含 `records` 列表（每项含 `deleted`、`record_id`）。

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

        飞书文档:
            [删除多条记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/batch_delete)

        Examples:
            >>> await client.bitable.records.batch_delete("bascnxxx", "tblcn1", ["rec1", "rec2"])  # doctest:+SKIP
            {'records': [{'deleted': True, 'record_id': 'rec1'}, ...]}  # noqa: E501
        """
        return await self._request_data(
            "POST",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/batch_delete",
            json={"records": record_ids},
        )

    async def batch_update(self, app_token: str, table_id: str, records: builtins.list[dict[str, Any]]) -> NestedDict:
        r"""
        批量更新记录。

        `records` 为待更新记录的列表，原样作为 `records` 字段并入请求体，每个元素需携带
        其 `record_id` 与待更新的 `fields`，形如 `{"record_id": "recxxx", "fields": {...}}`。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            records: 待更新记录列表，每个元素形如
                `{"record_id": "recxxx", "fields": {"Title": "new"}}`。

        Returns:
            批量更新结果数据，含更新后的 `records` 列表（每项含 `record_id`、`fields`）。

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

        飞书文档:
            [更新多条记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/batch_update)

        Examples:
            >>> recs = [{"record_id": "rec1", "fields": {"Title": "a"}}]
            >>> await client.bitable.records.batch_update("bascnxxx", "tblcn1", recs)  # doctest:+SKIP
            {'records': [{'record_id': 'rec1', 'fields': {'Title': 'a'}}]}  # noqa: E501
        """
        return await self._request_data(
            "POST",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/batch_update",
            json={"records": records},
        )

    async def create(self, app_token: str, table_id: str, fields: dict[str, Any]) -> NestedDict:
        r"""
        新增一条记录。

        `fields` 是记录的字段值映射，原样作为 `fields` 字段并入请求体，键为字段名、值为
        对应类型的字段值。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            fields: 记录字段值映射，例如 `{"Title": "hi", "Done": True}`。

        Returns:
            包含 `record` 字段的数据，`record` 内含新建记录的 `record_id`、`fields` 等字段。

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

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

        Examples:
            >>> await client.bitable.records.create("bascnxxx", "tblcn1", {"Title": "hi"})  # doctest:+SKIP
            {'record': {'record_id': 'recnew', 'fields': {'Title': 'hi'}}}  # noqa: E501
        """
        return await self._request_data(
            "POST",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records",
            json={"fields": fields},
        )

    async def delete(self, app_token: str, table_id: str, record_id: str) -> NestedDict:
        r"""
        删除一条记录。

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

        Returns:
            删除结果数据，含 `deleted`、`record_id` 等字段。

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

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

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

    async def get(self, app_token: str, table_id: str, record_id: str) -> NestedDict:
        r"""
        获取单条记录。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            record_id: 记录的 `record_id`。

        Returns:
            包含 `record` 字段的数据，`record` 内含 `record_id`、`fields` 等字段。

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

        飞书文档:
            [检索记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/get)

        Examples:
            >>> await client.bitable.records.get("bascnxxx", "tblcn1", "recxxx")  # doctest:+SKIP
            {'record': {'record_id': 'recxxx', 'fields': {'Title': 'hi'}}}  # noqa: E501
        """
        return await self._request_data(
            "GET",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}"
            f"/records/{quote_segment(record_id)}",
        )

    async def list(
        self,
        app_token: str,
        table_id: str,
        *,
        page_size: int = 50,
        max_items: int | None = None,
        view_id: str | None = None,
        filter: str | None = None,
        sort: str | None = None,
        field_names: str | None = None,
    ) -> builtins.list[NestedDict]:
        r"""
        列出数据表的记录。

        自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
        [feishu.consts.MAX_PAGE_SIZE][] 以内。仅将显式传入的可选查询参数并入请求，
        未设置的项会被省略。

        通过简单的列出接口返回记录，仅支持以查询参数传递 `view_id`、`filter`、`sort`、
        `field_names` 等基础筛选项；若需以结构化的筛选/排序请求体进行更丰富的复杂查询，
        请改用 [feishu.bitable.records.RecordsNamespace.search][]。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            page_size: 每页条数，默认为 50，超过上限时按上限截断。
            max_items: 最多返回的条数；为空表示返回全部。
            view_id: 视图 ID，按指定视图的筛选与排序返回记录；为空时省略该参数。
            filter: 筛选条件表达式；为空时省略该参数。
            sort: 排序条件；为空时省略该参数。
            field_names: 指定返回的字段集合；为空时省略该参数。

        Returns:
            记录数据列表，每项包含 `record_id`、`fields` 等字段。

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

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

        Examples:
            >>> await client.bitable.records.list("bascnxxx", "tblcn1")  # doctest:+SKIP
            [{'record_id': 'recxxx', 'fields': {'Title': 'hi'}}, ...]  # noqa: E501
        """
        params: dict[str, Any] = {}
        if view_id is not None:
            params["view_id"] = view_id
        if filter is not None:
            params["filter"] = filter
        if sort is not None:
            params["sort"] = sort
        if field_names is not None:
            params["field_names"] = field_names
        return await self._client.paginate_get(
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records",
            params=params,
            page_size=page_size,
            max_items=max_items,
        )

    async def search(
        self,
        app_token: str,
        table_id: str,
        body: dict[str, Any],
        *,
        page_size: int = 50,
        max_items: int | None = None,
    ) -> builtins.list[NestedDict]:
        r"""
        检索数据表的记录。

        自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
        [feishu.consts.MAX_PAGE_SIZE][] 以内。`page_token` 与 `page_size` 通过查询参数
        传递，而 `filter`、`sort`、`field_names`、`view_id`、`automatic_fields` 等检索
        条件经 `body` 以 JSON 请求体发送。

        通过检索接口以结构化的筛选/排序请求体进行更丰富的复杂查询；若仅需以查询参数传递
        `view_id`、`filter`、`sort`、`field_names` 等基础筛选项的简单列出，
        请改用 [feishu.bitable.records.RecordsNamespace.list][]。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            body: 检索条件请求体，原样作为 JSON 发送，例如
                `{"filter": {...}, "sort": [...], "field_names": [...]}`。
            page_size: 每页条数，默认为 50，超过上限时按上限截断。
            max_items: 最多返回的条数；为空表示返回全部。

        Returns:
            记录数据列表，每项包含 `record_id`、`fields` 等字段。

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

        飞书文档:
            [检索记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/search)

        Examples:
            >>> await client.bitable.records.search("bascnxxx", "tblcn1", {"field_names": ["Title"]})  # doctest:+SKIP
            [{'record_id': 'recxxx', 'fields': {'Title': 'hi'}}, ...]  # noqa: E501
        """

        async def fetch(page_token: str | None) -> NestedDict:
            params = {
                "page_size": min(page_size, MAX_PAGE_SIZE),
                "page_token": page_token,
            }
            return await self._client.request(
                "POST",
                f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/search",
                params=params,
                json=body,
            )

        return await paginate(fetch, max_items=max_items)

    async def update(self, app_token: str, table_id: str, record_id: str, fields: dict[str, Any]) -> NestedDict:
        r"""
        更新一条记录。

        `fields` 是记录的字段值映射，原样作为 `fields` 字段并入请求体；仅传入的字段会被
        更新，未传入的字段保持不变。

        Args:
            app_token: 多维表格的唯一标识 `app_token`。
            table_id: 数据表的 `table_id`。
            record_id: 待更新记录的 `record_id`。
            fields: 待更新的字段值映射，例如 `{"Title": "new"}`。

        Returns:
            包含 `record` 字段的数据，`record` 内含更新后记录的 `record_id`、`fields` 等字段。

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

        飞书文档:
            [更新记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/update)

        Examples:
            >>> await client.bitable.records.update("bascnxxx", "tblcn1", "recxxx", {"Title": "new"})  # doctest:+SKIP
            {'record': {'record_id': 'recxxx', 'fields': {'Title': 'new'}}}  # noqa: E501
        """
        return await self._request_data(
            "PUT",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}"
            f"/records/{quote_segment(record_id)}",
            json={"fields": fields},
        )

batch_create async

Python
batch_create(app_token: str, table_id: str, records: list[dict[str, Any]]) -> NestedDict

批量新增记录。

records 为待新增记录的列表，原样作为 records 字段并入请求体，每个元素形如 {"fields": {...}}。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
records
list[dict[str, Any]]

待新增记录列表，每个元素形如 {"fields": {"Title": "hi"}}。

 必需

返回：

类型 描述
NestedDict

批量新增结果数据，含新建的 records 列表（每项含 record_id、fields）。

引发：

类型 描述
FeishuError

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

新增多条记录

示例：

Python Console Session
1
2
3
>>> recs = [{"fields": {"Title": "a"}}, {"fields": {"Title": "b"}}]
>>> await client.bitable.records.batch_create("bascnxxx", "tblcn1", recs)
{'records': [{'record_id': 'rec1', ...}, {'record_id': 'rec2', ...}]}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
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
async def batch_create(self, app_token: str, table_id: str, records: builtins.list[dict[str, Any]]) -> NestedDict:
    r"""
    批量新增记录。

    `records` 为待新增记录的列表，原样作为 `records` 字段并入请求体，每个元素形如
    `{"fields": {...}}`。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        records: 待新增记录列表，每个元素形如 `{"fields": {"Title": "hi"}}`。

    Returns:
        批量新增结果数据，含新建的 `records` 列表（每项含 `record_id`、`fields`）。

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

    飞书文档:
        [新增多条记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/batch_create)

    Examples:
        >>> recs = [{"fields": {"Title": "a"}}, {"fields": {"Title": "b"}}]
        >>> await client.bitable.records.batch_create("bascnxxx", "tblcn1", recs)  # doctest:+SKIP
        {'records': [{'record_id': 'rec1', ...}, {'record_id': 'rec2', ...}]}  # noqa: E501
    """
    return await self._request_data(
        "POST",
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/batch_create",
        json={"records": records},
    )

batch_delete async

Python
batch_delete(app_token: str, table_id: str, record_ids: list[str]) -> NestedDict

批量删除记录。

record_ids 为待删除记录的 ID 列表，原样作为 records 字段并入请求体。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
record_ids
list[str]

待删除记录的 record_id 列表。

 必需

返回：

类型 描述
NestedDict

批量删除结果数据，含 records 列表（每项含 deleted、record_id）。

引发：

类型 描述
FeishuError

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

删除多条记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.batch_delete("bascnxxx", "tblcn1", ["rec1", "rec2"])
{'records': [{'deleted': True, 'record_id': 'rec1'}, ...]}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
 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
async def batch_delete(self, app_token: str, table_id: str, record_ids: builtins.list[str]) -> NestedDict:
    r"""
    批量删除记录。

    `record_ids` 为待删除记录的 ID 列表，原样作为 `records` 字段并入请求体。

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

    Returns:
        批量删除结果数据，含 `records` 列表（每项含 `deleted`、`record_id`）。

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

    飞书文档:
        [删除多条记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/batch_delete)

    Examples:
        >>> await client.bitable.records.batch_delete("bascnxxx", "tblcn1", ["rec1", "rec2"])  # doctest:+SKIP
        {'records': [{'deleted': True, 'record_id': 'rec1'}, ...]}  # noqa: E501
    """
    return await self._request_data(
        "POST",
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/batch_delete",
        json={"records": record_ids},
    )

batch_update async

Python
batch_update(app_token: str, table_id: str, records: list[dict[str, Any]]) -> NestedDict

批量更新记录。

records 为待更新记录的列表，原样作为 records 字段并入请求体，每个元素需携带 其 record_id 与待更新的 fields，形如 {"record_id": "recxxx", "fields": {...}}。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
records
list[dict[str, Any]]

待更新记录列表，每个元素形如 {"record_id": "recxxx", "fields": {"Title": "new"}}。

 必需

返回：

类型 描述
NestedDict

批量更新结果数据，含更新后的 records 列表（每项含 record_id、fields）。

引发：

类型 描述
FeishuError

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

更新多条记录

示例：

Python Console Session
1
2
3
>>> recs = [{"record_id": "rec1", "fields": {"Title": "a"}}]
>>> await client.bitable.records.batch_update("bascnxxx", "tblcn1", recs)
{'records': [{'record_id': 'rec1', 'fields': {'Title': 'a'}}]}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
async def batch_update(self, app_token: str, table_id: str, records: builtins.list[dict[str, Any]]) -> NestedDict:
    r"""
    批量更新记录。

    `records` 为待更新记录的列表，原样作为 `records` 字段并入请求体，每个元素需携带
    其 `record_id` 与待更新的 `fields`，形如 `{"record_id": "recxxx", "fields": {...}}`。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        records: 待更新记录列表，每个元素形如
            `{"record_id": "recxxx", "fields": {"Title": "new"}}`。

    Returns:
        批量更新结果数据，含更新后的 `records` 列表（每项含 `record_id`、`fields`）。

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

    飞书文档:
        [更新多条记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/batch_update)

    Examples:
        >>> recs = [{"record_id": "rec1", "fields": {"Title": "a"}}]
        >>> await client.bitable.records.batch_update("bascnxxx", "tblcn1", recs)  # doctest:+SKIP
        {'records': [{'record_id': 'rec1', 'fields': {'Title': 'a'}}]}  # noqa: E501
    """
    return await self._request_data(
        "POST",
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/batch_update",
        json={"records": records},
    )

create async

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

新增一条记录。

fields 是记录的字段值映射，原样作为 fields 字段并入请求体，键为字段名、值为 对应类型的字段值。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
fields
dict[str, Any]

记录字段值映射，例如 {"Title": "hi", "Done": True}。

 必需

返回：

类型 描述
NestedDict

包含 record 字段的数据，record 内含新建记录的 record_id、fields 等字段。

引发：

类型 描述
FeishuError

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

新增记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.create("bascnxxx", "tblcn1", {"Title": "hi"})
{'record': {'record_id': 'recnew', 'fields': {'Title': 'hi'}}}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
async def create(self, app_token: str, table_id: str, fields: dict[str, Any]) -> NestedDict:
    r"""
    新增一条记录。

    `fields` 是记录的字段值映射，原样作为 `fields` 字段并入请求体，键为字段名、值为
    对应类型的字段值。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        fields: 记录字段值映射，例如 `{"Title": "hi", "Done": True}`。

    Returns:
        包含 `record` 字段的数据，`record` 内含新建记录的 `record_id`、`fields` 等字段。

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

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

    Examples:
        >>> await client.bitable.records.create("bascnxxx", "tblcn1", {"Title": "hi"})  # doctest:+SKIP
        {'record': {'record_id': 'recnew', 'fields': {'Title': 'hi'}}}  # noqa: E501
    """
    return await self._request_data(
        "POST",
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records",
        json={"fields": fields},
    )

delete async

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

删除一条记录。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
record_id
str

待删除记录的 record_id。

 必需

返回：

类型 描述
NestedDict

删除结果数据，含 deleted、record_id 等字段。

引发：

类型 描述
FeishuError

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

删除记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.delete("bascnxxx", "tblcn1", "recxxx")
{'deleted': True, 'record_id': 'recxxx'}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
async def delete(self, app_token: str, table_id: str, record_id: str) -> NestedDict:
    r"""
    删除一条记录。

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

    Returns:
        删除结果数据，含 `deleted`、`record_id` 等字段。

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

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

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

get async

Python
get(app_token: str, table_id: str, record_id: str) -> NestedDict

获取单条记录。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
record_id
str

记录的 record_id。

 必需

返回：

类型 描述
NestedDict

包含 record 字段的数据，record 内含 record_id、fields 等字段。

引发：

类型 描述
FeishuError

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

检索记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.get("bascnxxx", "tblcn1", "recxxx")
{'record': {'record_id': 'recxxx', 'fields': {'Title': 'hi'}}}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
async def get(self, app_token: str, table_id: str, record_id: str) -> NestedDict:
    r"""
    获取单条记录。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        record_id: 记录的 `record_id`。

    Returns:
        包含 `record` 字段的数据，`record` 内含 `record_id`、`fields` 等字段。

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

    飞书文档:
        [检索记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/get)

    Examples:
        >>> await client.bitable.records.get("bascnxxx", "tblcn1", "recxxx")  # doctest:+SKIP
        {'record': {'record_id': 'recxxx', 'fields': {'Title': 'hi'}}}  # noqa: E501
    """
    return await self._request_data(
        "GET",
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}"
        f"/records/{quote_segment(record_id)}",
    )

list async

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

列出数据表的记录。

自动翻页并将各页结果拼接为单个列表返回。page_size 会被限制在 [feishu.consts.MAX_PAGE_SIZE][] 以内。仅将显式传入的可选查询参数并入请求， 未设置的项会被省略。

通过简单的列出接口返回记录，仅支持以查询参数传递 view_id、filter、sort、 field_names 等基础筛选项；若需以结构化的筛选/排序请求体进行更丰富的复杂查询， 请改用 feishu.bitable.records.RecordsNamespace.search。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
page_size
int

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

 50
max_items
int | None

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

 None
view_id
str | None

视图 ID，按指定视图的筛选与排序返回记录；为空时省略该参数。

 None
filter
str | None

筛选条件表达式；为空时省略该参数。

 None
sort
str | None

排序条件；为空时省略该参数。

 None
field_names
str | None

指定返回的字段集合；为空时省略该参数。

 None

返回：

类型 描述
list[NestedDict]

记录数据列表，每项包含 record_id、fields 等字段。

引发：

类型 描述
FeishuError

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

列出记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.list("bascnxxx", "tblcn1")
[{'record_id': 'recxxx', 'fields': {'Title': 'hi'}}, ...]  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
async def list(
    self,
    app_token: str,
    table_id: str,
    *,
    page_size: int = 50,
    max_items: int | None = None,
    view_id: str | None = None,
    filter: str | None = None,
    sort: str | None = None,
    field_names: str | None = None,
) -> builtins.list[NestedDict]:
    r"""
    列出数据表的记录。

    自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
    [feishu.consts.MAX_PAGE_SIZE][] 以内。仅将显式传入的可选查询参数并入请求，
    未设置的项会被省略。

    通过简单的列出接口返回记录，仅支持以查询参数传递 `view_id`、`filter`、`sort`、
    `field_names` 等基础筛选项；若需以结构化的筛选/排序请求体进行更丰富的复杂查询，
    请改用 [feishu.bitable.records.RecordsNamespace.search][]。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        page_size: 每页条数，默认为 50，超过上限时按上限截断。
        max_items: 最多返回的条数；为空表示返回全部。
        view_id: 视图 ID，按指定视图的筛选与排序返回记录；为空时省略该参数。
        filter: 筛选条件表达式；为空时省略该参数。
        sort: 排序条件；为空时省略该参数。
        field_names: 指定返回的字段集合；为空时省略该参数。

    Returns:
        记录数据列表，每项包含 `record_id`、`fields` 等字段。

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

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

    Examples:
        >>> await client.bitable.records.list("bascnxxx", "tblcn1")  # doctest:+SKIP
        [{'record_id': 'recxxx', 'fields': {'Title': 'hi'}}, ...]  # noqa: E501
    """
    params: dict[str, Any] = {}
    if view_id is not None:
        params["view_id"] = view_id
    if filter is not None:
        params["filter"] = filter
    if sort is not None:
        params["sort"] = sort
    if field_names is not None:
        params["field_names"] = field_names
    return await self._client.paginate_get(
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records",
        params=params,
        page_size=page_size,
        max_items=max_items,
    )

search async

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

检索数据表的记录。

自动翻页并将各页结果拼接为单个列表返回。page_size 会被限制在 [feishu.consts.MAX_PAGE_SIZE][] 以内。page_token 与 page_size 通过查询参数 传递，而 filter、sort、field_names、view_id、automatic_fields 等检索 条件经 body 以 JSON 请求体发送。

通过检索接口以结构化的筛选/排序请求体进行更丰富的复杂查询；若仅需以查询参数传递 view_id、filter、sort、field_names 等基础筛选项的简单列出， 请改用 feishu.bitable.records.RecordsNamespace.list。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
body
dict[str, Any]

检索条件请求体，原样作为 JSON 发送，例如 {"filter": {...}, "sort": [...], "field_names": [...]}。

 必需
page_size
int

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

 50
max_items
int | None

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

 None

返回：

类型 描述
list[NestedDict]

记录数据列表，每项包含 record_id、fields 等字段。

引发：

类型 描述
FeishuError

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

检索记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.search("bascnxxx", "tblcn1", {"field_names": ["Title"]})
[{'record_id': 'recxxx', 'fields': {'Title': 'hi'}}, ...]  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
async def search(
    self,
    app_token: str,
    table_id: str,
    body: dict[str, Any],
    *,
    page_size: int = 50,
    max_items: int | None = None,
) -> builtins.list[NestedDict]:
    r"""
    检索数据表的记录。

    自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
    [feishu.consts.MAX_PAGE_SIZE][] 以内。`page_token` 与 `page_size` 通过查询参数
    传递，而 `filter`、`sort`、`field_names`、`view_id`、`automatic_fields` 等检索
    条件经 `body` 以 JSON 请求体发送。

    通过检索接口以结构化的筛选/排序请求体进行更丰富的复杂查询；若仅需以查询参数传递
    `view_id`、`filter`、`sort`、`field_names` 等基础筛选项的简单列出，
    请改用 [feishu.bitable.records.RecordsNamespace.list][]。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        body: 检索条件请求体，原样作为 JSON 发送，例如
            `{"filter": {...}, "sort": [...], "field_names": [...]}`。
        page_size: 每页条数，默认为 50，超过上限时按上限截断。
        max_items: 最多返回的条数；为空表示返回全部。

    Returns:
        记录数据列表，每项包含 `record_id`、`fields` 等字段。

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

    飞书文档:
        [检索记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/search)

    Examples:
        >>> await client.bitable.records.search("bascnxxx", "tblcn1", {"field_names": ["Title"]})  # doctest:+SKIP
        [{'record_id': 'recxxx', 'fields': {'Title': 'hi'}}, ...]  # noqa: E501
    """

    async def fetch(page_token: str | None) -> NestedDict:
        params = {
            "page_size": min(page_size, MAX_PAGE_SIZE),
            "page_token": page_token,
        }
        return await self._client.request(
            "POST",
            f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}/records/search",
            params=params,
            json=body,
        )

    return await paginate(fetch, max_items=max_items)

update async

Python
update(app_token: str, table_id: str, record_id: str, fields: dict[str, Any]) -> NestedDict

更新一条记录。

fields 是记录的字段值映射，原样作为 fields 字段并入请求体；仅传入的字段会被 更新，未传入的字段保持不变。

参数：

名称 类型 描述 默认
app_token
str

多维表格的唯一标识 app_token。

 必需
table_id
str

数据表的 table_id。

 必需
record_id
str

待更新记录的 record_id。

 必需
fields
dict[str, Any]

待更新的字段值映射，例如 {"Title": "new"}。

 必需

返回：

类型 描述
NestedDict

包含 record 字段的数据，record 内含更新后记录的 record_id、fields 等字段。

引发：

类型 描述
FeishuError

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

更新记录

示例：

Python Console Session
1
2
>>> await client.bitable.records.update("bascnxxx", "tblcn1", "recxxx", {"Title": "new"})
{'record': {'record_id': 'recxxx', 'fields': {'Title': 'new'}}}  # noqa: E501
源代码位于： feishu/bitable/records.py
Python
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
async def update(self, app_token: str, table_id: str, record_id: str, fields: dict[str, Any]) -> NestedDict:
    r"""
    更新一条记录。

    `fields` 是记录的字段值映射，原样作为 `fields` 字段并入请求体；仅传入的字段会被
    更新，未传入的字段保持不变。

    Args:
        app_token: 多维表格的唯一标识 `app_token`。
        table_id: 数据表的 `table_id`。
        record_id: 待更新记录的 `record_id`。
        fields: 待更新的字段值映射，例如 `{"Title": "new"}`。

    Returns:
        包含 `record` 字段的数据，`record` 内含更新后记录的 `record_id`、`fields` 等字段。

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

    飞书文档:
        [更新记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/update)

    Examples:
        >>> await client.bitable.records.update("bascnxxx", "tblcn1", "recxxx", {"Title": "new"})  # doctest:+SKIP
        {'record': {'record_id': 'recxxx', 'fields': {'Title': 'new'}}}  # noqa: E501
    """
    return await self._request_data(
        "PUT",
        f"bitable/v1/apps/{quote_segment(app_token)}/tables/{quote_segment(table_id)}"
        f"/records/{quote_segment(record_id)}",
        json={"fields": fields},
    )