用途:管理企业微信智能表格中的记录(行数据),提供增删改查能力。适用查询子表全部记录、添加一行或多行、更新已有记录、删除记录。
调用方式:所有操作用 wecom-cli 命令完成,品类为 doc,格式为 wecom-cli doc <tool_name> '<json_params>'。定位文档可用 docid 或 url 二选一。
主要能力与用法: 查询记录:smartsheet_get_records,传入 docid 或 url 加 sheet_id。 添加记录:smartsheet_add_records,单次建议 500 行内;调用前需先通过 smartsheet_get_fields 了解字段类型,尤其 field_type,单选/多选字段需匹配已有选项 id。 更新记录:smartsheet_update_records,单次建议 500 行内,需提供 record_id(由 smartsheet_get_records 获取);可用 key_type 指定 values 的 key 为字段标题(CELL_VALUE_KEY_TYPE_FIELD_TITLE)或字段 ID(CELL_VALUE_KEY_TYPE_FIELD_ID)。创建时间、最后编辑时间、创建人、最后编辑人字段不可更新。 删除记录:smartsheet_delete_records,单次必须在 500 行内,操作不可逆,record_id 由 smartsheet_get_records 获取。
返回格式:返回 JSON,含 errcode(0 成功,非 0 失败)、errmsg。errcode 非 0 时可重试 1 次,仍失败则将 errcode 与 errmsg 展示给用户。
典型工作流:读取数据直接调用 smartsheet_get_records;写入数据先 smartsheet_get_fields 了解列类型,若涉及成员(USER)字段,先通过 wecomcli-lookup-contact 的 get_userlist 查找 userid 再写入;更新数据先获取 record_id,涉及 USER 字段同样先查 userid;删除数据先确认 record_id。
限制:成员(USER)类型字段需填 user_id,不能直接用姓名,必须先按姓名查到 userid。单次行数有上限。创建/编辑时间与人员字段不可更新。删除不可逆。