
批量导入最危险的时刻,往往是客户端没有收到结果。屏幕显示超时,服务端却可能已经接收请求、创建提案,甚至完成合并。此时重新生成一批请求,可能把同一份资料写成两组正式记录。
安全恢复要先回答两个问题:原请求到了哪一步,哪些业务对象已经存在。请求幂等键帮助找回同一次提交,业务稳定键帮助识别同一个对象;两者各有用途。
在发送前建立批次清单
Busabase的实时 OpenAPI规定,bulk-change-request一次最多接收1000条records,并把它们放进同一个ChangeRequest。更大的导入应拆成可检查的批次,或使用适合大规模数据的专门导入方式。
清单至少保留目标Space和Base、提交身份、源文件或内容摘要、每批包含的业务稳定键、原请求正文、idempotencyKey及返回的CR ID。正文发生变化时,清单应能显示这已不是原来的同一次提交。不要把真实密钥放进日志。

结构示意 · 可调整的工作方法
幂等键标识一次请求,业务键标识一个对象
bulk创建接口的idempotencyKey按Base和提交者划分作用域。同一作用域内使用同一个键重试,会返回最初创建的CR,帮助处理响应丢失。它并不为整个Base自动建立业务唯一约束。
业务稳定键则来自资料本身,例如源系统中已有的对象标识。导入前检查这些键是否重复、是否已有对应canonical记录;恢复后再用它们核验唯一性。不要用名称相似或显示标题相同来替代稳定身份。
超时后先找原CR
已拿到CR ID时,直接读取原CR,检查状态、操作和对应记录。只有请求没有得到响应时,才按已保存的原正文、原目标和原幂等键恢复同一次提交。不要把内容重排、删改后仍当作相同请求盲目重用旧键。
in_review、approved和merged表示不同阶段。待审提案不等于当前正式记录,获批也不等于已经合并。先查原提案与canonical结果,再决定还需要执行什么。暂时查不到正式记录,不能单独证明原请求从未到达。

结构示意 · 可调整的工作方法
多批任务逐批验收
一次bulk创建是一个CR,不应把多个批次推断为一个跨批事务。为每批分别记录“请求结果未知”“已创建CR”“等待审核”“已合并”“回读通过”等状态;这些是建议的导入台账状态,需要由你的脚本或Agent维护。
前面的批次已通过、后面的批次超时,就从未确认的批次恢复。不要清空整张表后重来,也不要把整个文件换一个新键再上传。最终逐业务键检查:是否恰好有一个记录、必要字段是否准确、缺失和冲突是否已列明。
更新已有记录要保留版本边界
找到已有对象后,不应继续用create制造另一个副本。更新使用recordId,带上当前baseCommitId,只提交需要修改的fields。稀疏更新中省略的字段保持原值;null用于清空字段,因此不能把未提供数据一律转换成null。
写入权限也影响恢复路径。write权限可以即时合并,proposal-only权限会等待审核;需要强制人审时,应按支持的接口显式保留审核。重试不能成为绕过审核或覆盖并发修改的理由。

结构示意 · 可调整的工作方法
把恢复规则交给Agent,也保留可查产物
可以这样要求已连接的Agent:
为指定Base准备导入清单,先按业务稳定键查重。每批保存原正文、独立幂等键和原CR。超时后先核原CR及canonical,不换键重建;未确认的批次停止后续依赖操作。合并后逐键回读数量与必要字段,返回缺失、重复、冲突和剩余批次。
先用有代表性的小范围资料走通发送、审核、回读与中断恢复,再扩大规模。实际成果是批次清单、原提案链接和唯一性检查结果,而不只是“上传成功”。通过REST API指南确认接口与权限,让同一份业务资料在重试后仍有清楚的身份和历史。