飞书多维表格自动化：使用 Python SDK 动态创建列并写入数据

在自动化办公场景中，我们经常需要根据业务逻辑动态地向飞书多维表格（Bitable）中添加字段，并对指定行进行数据填充。本文将分享如何使用 lark-oapi Python SDK 高效完成这一操作。

1. 核心流程概述

实现“加入新列并填值”的自动化任务主要分为两个核心阶段：

1. 定义并创建字段 (Field Creation)：通过 app_table_field.create 接口，定义列名及其数据类型（如文本、数字等）。
2. 更新行记录 (Record Update)：通过 app_table_record.update 接口，利用 record_id 对特定行进行定向赋值。

2. 环境准备

确保你的开发环境中已安装飞书官方 SDK：

pip install lark-oapi

3. 完整代码实现

在编写代码时，需要注意 lark-oapi SDK 的 RequestBuilder 统一使用 .request_body() 方法来封装请求参数。

root@device:/#

import json
import lark_oapi as lark
from lark_oapi.api.bitable.v1 import *

def automate_bitable():
    # 1. 初始化客户端
    # 建议生产环境将 Token 放入环境变量
    client = lark.Client.builder() \
        .enable_set_token(True) \
        .log_level(lark.LogLevel.INFO) \
        .build()

    # 配置基础信息
    APP_TOKEN = "W4M123123OXs8gzFcQWC51234"
    TABLE_ID = "tblB12313j1234"
    USER_TOKEN = "u-fe.W0123123aHmoJjNMsIW416GlAlhghPEaaExy123"
    
    option = lark.RequestOption.builder() \
        .user_access_token(USER_TOKEN) \
        .build()

    # --- 步骤 A: 创建新列 "测试1" ---
    # type(1) 代表多行文本类型
    field_data = AppTableField.builder() \
        .field_name("测试1") \
        .type(1) \
        .build()

    field_request = CreateAppTableFieldRequest.builder() \
        .app_token(APP_TOKEN) \
        .table_id(TABLE_ID) \
        .request_body(field_data) \
        .build()

    field_resp = client.bitable.v1.app_table_field.create(field_request, option)
    
    if field_resp.success():
        print(f"成功创建列: {field_data.field_name}")
    else:
        print(f"列处理信息: {field_resp.msg} (若已存在可忽略)")

    # --- 步骤 B: 在指定行填入数据 ---
    # 假设我们要操作的行 ID 为 recDRX5etH
    TARGET_RECORD_ID = "recDRX5etH"
    
    record_data = AppTableRecord.builder() \
        .fields({
            "测试1": "111"  # 键名为列名，值为对应内容
        }) \
        .build()

    record_request = UpdateAppTableRecordRequest.builder() \
        .app_token(APP_TOKEN) \
        .table_id(TABLE_ID) \
        .record_id(TARGET_RECORD_ID) \
        .request_body(record_data) \
        .build()

    record_resp = client.bitable.v1.app_table_record.update(record_request, option)

    if record_resp.success():
        print(f"成功更新记录 {TARGET_RECORD_ID}，填入值: 111")
    else:
        print(f"数据更新失败: {record_resp.msg}")

if __name__ == "__main__":
    automate_bitable()

4. 关键点深度解析

字段类型说明

在 AppTableField 中，type 参数决定了列的属性。常见类型如下：

• 1: 多行文本
• 2: 数字
• 3: 单选
• 5: 日期（写入时需传入毫秒级时间戳）

关于字段唯一性

飞书多维表格不允许在同一张表内创建两个同名的列。在实际业务中，建议在创建前先调用 field.list 接口检查列是否存在，或者通过 try...except 或响应码判断来增强代码的鲁棒性。

增量更新机制

app_table_record.update 属于 PATCH 行为。你只需要在 fields 字典中传入你想要修改的列，其他未提及的列数据会保持不变，不会被覆盖。

5. 总结

通过 Python SDK 操作飞书多维表格，可以将繁琐的录入工作自动化。本次测试成功验证了从结构变更（加列）到内容填充（写值）的完整闭环，为后续复杂的业务自动化打下了基础。