钉钉多维表（AI 表格）

钉钉多维表（AI 表格） 是一个办公协同插件，以插件能力的形式出现在指令树「扩展能力」中。安装或内置加载后，可把插件里的节点拖到工作流画布使用。

插件标识：rpa-plugin-dingtalk-bitable
插件分类：办公协同插件
节点数量：10 个

先选使用方式

方式	怎么用	适合人群
可视化编排（推荐）	在「扩展能力」中找到 钉钉多维表（AI 表格），拖入需要的节点并填写参数	大多数用户，适合按表单配置插件能力
代码编排（执行指令 XML）	通过「执行指令（XML）」调用节点的 type 与参数	需要动态拼装、循环调用或批量处理的用户

什么时候用？

• 覆盖钉钉 AI 表格（多维表 / Notable）全套原子节点：连通性 / 列表 / 表 meta / 记录搜索 / 记录单条与批量 CRUD / 表 Schema 管理。需先在「连接管理」配置 dingtalk-app（AppKey + AppSecret + 操作人 unionId/userId），节点通过 connectionId 引用即可，无需手动管理 accessToken / operatorId。
• 需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

• 需要先配置连接：dingtalk-app。
• 办公协同类能力需要确认文件、表格、空间或数据库的访问权限。
• 建议先运行连通性、查询或只读节点，确认权限和参数正确后再执行写入类节点。

连接配置

连接类型	名称	说明
dingtalk-app	dingtalk-app	通过 AppKey + AppSecret 调用钉钉 AI 表格（多维表 / Notable）OpenAPI

节点总览

节点名称	节点标识	说明
连通性测试（钉钉）	DingtalkBitablePing	向钉钉 OpenAPI 换一次 accessToken 验证 AppKey/AppSecret 凭据可用
列出数据表（钉钉）	ListDingtalkBitableSheets	列出指定多维表 (base) 内的所有数据表。常用作其它节点前的准备步骤，先拿到 sheetId / sheetName 再操作记录
获取数据表元信息（钉钉）	GetDingtalkBitableSheetMeta	获取指定数据表的基础信息与所有字段定义（含字段类型、property）
搜索记录（钉钉）	SearchDingtalkBitableRecords	在数据表中按条件查询多行记录，支持过滤、字段裁剪、分页（手动 nextToken 或自动翻页）
获取单条记录（钉钉）	GetDingtalkBitableRecord	按 recordId 获取单条记录的字段值
新增记录（钉钉）	CreateDingtalkBitableRecords	在指定数据表中新增 1~N 行记录；超过 50 条自动分批；可传 fields 单条或 records 批量
更新记录（钉钉）	UpdateDingtalkBitableRecords	更新 1~N 行记录；超过 50 条自动分批；可传 recordId+fields 单条或 records 批量
删除记录（钉钉）	DeleteDingtalkBitableRecords	按 recordId 列表删除 1~N 行记录；超过 100 条自动分批 注意：删除记录不可恢复；批量删除中途失败时请根据 data.deletedRecordIds/data.deletedCount 判断已删除范围。
新建数据表（钉钉）	CreateDingtalkBitableSheet	在多维表中新建一个数据表，可选初始字段列表
删除数据表（钉钉）	DeleteDingtalkBitableSheet	在多维表中删除一个数据表（不可恢复）

节点参数与输出

连通性测试（钉钉）

• 节点标识： DingtalkBitablePing
• 节点说明： 向钉钉 OpenAPI 换一次 accessToken 验证 AppKey/AppSecret 凭据可用
• XML 示例：

<DingtalkBitablePing connectionId="" outKey="pingResult" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-	在「设置 → 集成与连接」中配置的钉钉自建应用连接
输出变量名	outKey	output	否	pingResult	ping 结果将写入此变量
失败时抛错	failOnError	boolean	否	true	true：调用失败抛 节点错误 中断流程；false：失败结果写入 outKey 后继续，由后续 if 节点判断 ok 字段

输出字段：

字段	类型	说明
pingResult	object	成功：{ ok:true, data:{ connected:true }, statusCode, attempts, durationMs, requestId? }；失败：{ ok:false, error, code, category, hint? }

列出数据表（钉钉）

• 节点标识： ListDingtalkBitableSheets
• 节点说明： 列出指定多维表 (base) 内的所有数据表。常用作其它节点前的准备步骤，先拿到 sheetId / sheetName 再操作记录
• XML 示例：

<ListDingtalkBitableSheets connectionId="" url="" outKey="sheets" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-	粘贴 https://alidocs.dingtalk.com/i/nodes/<baseId>；与 baseId 二选一
baseId（替代 url）	baseId	string	否	-	直接传多维表 ID；不填则从 url 解析
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-	可选；不填走连接的 defaultOperatorUnionId / defaultOperatorUserId
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-	可选；与 operatorUnionId 二选一，本插件会自动解析为 unionId 并缓存
输出变量名	outKey	output	否	sheets
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
sheets	object	{ ok:true, data:{ sheets:[{sheetId, name}], total }, statusCode, attempts, durationMs, requestId? }

获取数据表元信息（钉钉）

• 节点标识： GetDingtalkBitableSheetMeta
• 节点说明： 获取指定数据表的基础信息与所有字段定义（含字段类型、property）
• XML 示例：

<GetDingtalkBitableSheetMeta connectionId="" url="" sheetIdOrName="" outKey="sheetMeta" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-	与 baseId 二选一
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-	钉钉支持直接传中文名（如 “任务表”），也支持表 ID
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	sheetMeta
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
sheetMeta	object	{ ok:true, data:{ sheet:{sheetId,name}, fields:[{fieldId,name,type,property?}] }, statusCode, attempts, durationMs, requestId? }

搜索记录（钉钉）

• 节点标识： SearchDingtalkBitableRecords
• 节点说明： 在数据表中按条件查询多行记录，支持过滤、字段裁剪、分页（手动 nextToken 或自动翻页）
• XML 示例：

<SearchDingtalkBitableRecords connectionId="" url="" sheetIdOrName="" pageSize="100" outKey="records" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-	与 baseId 二选一
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
筛选条件	filter	json	否	-	JSON：{ combination:“and”|“or”, conditions:[{ field:“字段名”, operator:“equal|contain|…”, value:[…] }] }
返回字段列表	fieldNames	string	否	-	限定返回列；JSON 数组或逗号分隔；单次最多 100 个
每页条数	pageSize	number	否	100	1~100；默认 100
分页游标	nextToken	string	否	-	上次返回的 nextToken，手动翻页时使用；启用 autoPaginate 时忽略
自动翻页	autoPaginate	boolean	否	true	true：自动翻页，直到无更多数据或到达 maxRecords/maxPages 上限
最大返回行数	maxRecords	number	否	1000	autoPaginate=true 时的总数上限；默认 1000，上限 50000
最多翻页数	maxPages	number	否	50	autoPaginate=true 时防止无限翻页；默认 50，上限 1000
输出变量名	outKey	output	否	records
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
records	object	{ ok:true, data:{ records:[{id, fields, createdBy?, lastModifiedBy?, createdTime?, lastModifiedTime?}], total, hasMore, pageCount, nextToken? }, statusCode, attempts, durationMs, requestId? }

获取单条记录（钉钉）

• 节点标识： GetDingtalkBitableRecord
• 节点说明： 按 recordId 获取单条记录的字段值
• XML 示例：

<GetDingtalkBitableRecord connectionId="" url="" sheetIdOrName="" recordId="" outKey="record" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-
记录 ID	recordId	string	是	-	recxxxxxxxx
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	record
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
record	object	{ ok:true, data:{ id, fields, createdBy?, lastModifiedBy?, createdTime?, lastModifiedTime? }, statusCode, attempts, durationMs, requestId? }

新增记录（钉钉）

• 节点标识： CreateDingtalkBitableRecords
• 节点说明： 在指定数据表中新增 1~N 行记录；超过 50 条自动分批；可传 fields 单条或 records 批量
• XML 示例：

<CreateDingtalkBitableRecords connectionId="" url="" sheetIdOrName="" records="" outKey="createResult" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-
记录数组	records	json	否	-	JSON 数组；支持两种形态：[{“fields”:{“标题”:“x”}}] 或扁平 [{“标题”:“x”,“数字”:1}]
单条快捷写法（替代 records）	fields	json	否	-	JSON 对象；只写一行时可用此字段；与 records 二选一
幂等键 clientToken	clientToken	string	否	-	UUID v4 字符串；不填则随机生成。同一 token 重复调用幂等不会重复写入
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	createResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
createResult	object	{ ok:true, data:{ records:[{id}], total }, statusCode, attempts, durationMs, requestId? }

更新记录（钉钉）

• 节点标识： UpdateDingtalkBitableRecords
• 节点说明： 更新 1~N 行记录；超过 50 条自动分批；可传 recordId+fields 单条或 records 批量
• XML 示例：

<UpdateDingtalkBitableRecords connectionId="" url="" sheetIdOrName="" records="" outKey="updateResult" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-
记录数组	records	json	否	-	JSON：[{“id”:“recXxx”,“fields”:{“状态”:“完成”}}]
单条快捷：记录 ID	recordId	string	否	-	与 records 二选一；与 fields 配合使用
单条快捷：字段对象	fields	json	否	-	与 recordId 配合使用，等价于 records=[{id:recordId, fields:fields}]
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	updateResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
updateResult	object	{ ok:true, data:{ records:[{id}], total }, statusCode, attempts, durationMs, requestId? }

删除记录（钉钉）

• 节点标识： DeleteDingtalkBitableRecords
• 节点说明： 按 recordId 列表删除 1~N 行记录；超过 100 条自动分批 注意：删除记录不可恢复；批量删除中途失败时请根据 data.deletedRecordIds/data.deletedCount 判断已删除范围。
• XML 示例：

<DeleteDingtalkBitableRecords connectionId="" url="" sheetIdOrName="" recordIds="" outKey="deleteResult" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-
记录 ID 列表	recordIds	json	否	-	JSON 数组或逗号分隔字符串：[“recXxx”,“recYyy”]
单条快捷：记录 ID	recordId	string	否	-	与 recordIds 二选一，删除单条
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	deleteResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
deleteResult	object	{ ok:true, data:{ success:true, requestedCount, deletedCount }, statusCode, attempts, durationMs, requestId? }；若钉钉返回 data.success=false，则返回 { ok:false, code:“delete.success.false”, category:“data”, hint, rawMsg } 并受 failOnError 控制

新建数据表（钉钉）

• 节点标识： CreateDingtalkBitableSheet
• 节点说明： 在多维表中新建一个数据表，可选初始字段列表
• XML 示例：

<CreateDingtalkBitableSheet connectionId="" url="" name="" outKey="newSheet" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-
baseId	baseId	string	否	-
数据表名	name	string	是	-	新数据表
初始字段	fields	json	否	-	JSON 数组 [{“name”:“标题”,“type”:“text”,“property”:{}}]；type 支持 text/number/singleSelect/multiSelect/date/checkbox/member/department/link 等
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	newSheet
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
newSheet	object	{ ok:true, data:{ sheetId, name }, statusCode, attempts, durationMs, requestId? }

删除数据表（钉钉）

• 节点标识： DeleteDingtalkBitableSheet
• 节点说明： 在多维表中删除一个数据表（不可恢复）
• XML 示例：

<DeleteDingtalkBitableSheet connectionId="" url="" sheetIdOrName="" outKey="deleteResult" />

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
多维表链接	url	string	否	-
baseId	baseId	string	否	-
数据表（ID 或名称）	sheetIdOrName	string	是	-
操作人 unionId（覆盖连接）	operatorUnionId	string	否	-
操作人 userId（覆盖连接）	operatorUserId	string	否	-
输出变量名	outKey	output	否	deleteResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
deleteResult	object	{ ok:true, data:{ deleted:true }, statusCode, attempts, durationMs, requestId? }

成功标准

• 节点运行状态为成功。
• 输出变量中包含预期字段，且可被下游节点引用。
• 对外部系统有写入动作的节点，目标系统中的数据状态与配置一致。

失败排查

现象 / 报错	可能原因	处理建议
找不到插件分组	插件未安装、未加载或当前端不是桌面客户端	在「扩展能力」中刷新/重新扫描插件，必要时重启客户端。
连接或鉴权失败	连接配置缺失、令牌过期或权限不足	重新配置连接，确认账号具备对应资源权限。
查询结果为空	筛选条件过窄、目标资源为空或页面状态不正确	放宽条件，检查资源 ID、日期范围和页面登录态。
写入类操作失败	参数格式不符合平台要求或目标资源不可写	先用少量测试数据验证，再检查必填字段、ID 和权限。

相关说明

• 插件能力由桌面端扩展能力机制加载，和普通后端指令树不是同一数据源。
• 插件页按插件维度整理；每个节点的帮助入口会跳到所属插件页，页面内可查节点标识、参数和输出。