比對歷程並還原資料列
情境：訂單狀態被誤改，你要先找出正確版本、檢查差異，再以不破壞稽核軌跡的方式還原。
前置條件
讀取歷程需要該資料列的 read 權限；restore 另外需要 edit 權限。本例使用聊天室 11111111-1111-4111-8111-111111111111、資料表 22222222-2222-4222-8222-222222222222 與資料列 33333333-3333-4333-8333-333333333333。以下 private 請求使用使用者 access token。
歷程請求不接受房間參數。acting_chatroom_id 已於 2026-07-29 從所有 custom-table 路由移除；現在加上它會拿到 200 而且什麼都不改變，因為未知的 query parameter 會被丟棄。在部門表上，呼叫者的讀取等級與列過濾是把他持有的每一筆 chatroom grant 合併後解析出來的，因此被兩個房間授權的成員，看得到任一房間所授權之列的歷程。若某列被解析後的 read ACL 隱藏，其歷程回 404 Record not found——與該列從未存在無法區分，因為歷程快照帶有完整的列資料。
步驟
1. 列出單筆資料列歷程
history.record 以最新項目優先回傳歷程，但版本號仍隨時間遞增。用 limit 與 offset 分頁，不要以陣列位置當成 version。
GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/33333333-3333-4333-8333-333333333333/history?limit=50&offset=0若你要先從整張表找某個變更，也可用 history.table 的 change_type 與 record_id query 篩選。
2. 讀取候選版本快照
假設第 1 版是已知正確狀態，先透過 history.version 取回完整快照。快照資料 key 是穩定的內部欄位 ID；用表格 settings.column_mapping 轉成顯示名稱供人檢查。
GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/33333333-3333-4333-8333-333333333333/history/13. 明確比對兩個版本
在 history.diff 中，路徑版本是 from_version，compare_to 是 to_version；下列請求顯示第 3 版到第 1 版需要改變的欄位。對調兩者會反轉 old 與 new。
GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/33333333-3333-4333-8333-333333333333/history/3/diff?compare_to=1diff 也使用內部欄位 ID，且會移除目前呼叫者不可見的欄位。
4. 還原已確認的版本
history.restoreVersion 不帶 request body；它不會覆寫或刪除既有歷程，而會以 change_type: "revert" 建立下一個版本。
POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/33333333-3333-4333-8333-333333333333/history/1/restore正常套用時，回應包含 restored_from_version、new_version 與更新後 record。只有 scalar cells 會還原；若 links_not_restored 是 true，現有 link 關係仍保持不變，應另外檢查。
5. 處理 approval-gated restore
若資料表的 require_approval 規則命中 restore，步驟 4 會回傳結構化 approval_required 衝突，內含 process_id、rule_id 與 staged_change_id。這代表還原已被暫存，並非已套用，也不是要重送 restore。
把 process_id 交給核准流程，等待核准或拒絕。核准後再執行步驟 1；新出現的 revert version 才是 restore 已生效的證據。拒絕時歷程不會增加 restore version。
6. 驗證新版本
再次列出 record history，取得新的 version，再用 history.version 讀取它。確認 scalar values 與第 1 版相同、change_type 是 revert，並把新版本號寫入你的稽核紀錄。
你會看到什麼
立即 restore 會回傳新的單調遞增版本；受核准控制時，先看到 staged process，核准後才看到新版本。舊版本一直保留，因此可追溯誰在何時還原到哪個 snapshot。
常見錯誤
請直接查看資料列歷程錯誤表、版本快照錯誤表、差異錯誤表與還原錯誤表。
試試看
在 API Playground 依序執行 history.record、history.version、history.diff 與 history.restoreVersion；不要在有核准規則的正式資料上用未審查的版本測試。