Skip to Content
核心概念自然鍵匯入 v2

自然鍵匯入 v2

匯入 v2 是寫入既有 Custom Tables 的有界、同步且原子的 REST 載入，支援自然鍵更新、原生連結解析、一般子資料列與可重用對應。它不取代非同步檔案匯入；原本只新增的途徑仍最多接受 50,000 筆對應後資料列。沒有新增 Agent／MCP 檔案匯入或遷移工具。

分隔文字擷取支援逗號、分號、tab 與直線，採 1,024 字元判斷／逗號 fallback；精確 decimal 來源與 BOM／多行規則仍見檔案匯入指南。

兩種輸入途徑、三個範圍

以下 T 代表 /private/module/custom_tables/company/tables/{table_id}、/private/module/custom_tables/department/{department_id}/tables/{table_id} 或 /private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}。

  • POST T/import-v2/{sid} 使用擷取工作階段與預覽的 signature（64 個小寫十六進位字元）。每個子表選擇另帶自己的 table_id、sid、signature 與對應選擇；子表與主表同範圍，於主表之後執行。
  • POST T/import-v2/migration 直接接受 JSON rows: [{data, children?}]，不需要擷取工作階段，固定採用已宣告唯一鍵語意。data 可放字串／數字／布林／null 純量；精確 decimal 必須使用字串。

兩種途徑均限制主列加子列合計最多 1,000 筆、16 個子表。沒有 worker 選項、寫入 ticket 或 skip_invalid 模式。成功回傳 inserted、updated 與 rows: [{table_id, record_id, source_index, disposition}]；來源索引以各表輸入為單位，從零起算，disposition 為 insert 或 update。

對應與自然鍵

{
  "mapping": {
    "mode": "upsert",
    "column_map": {"Code": "Code", "Region": "Region", "Qty": "Qty"},
    "key_columns": ["Code", "Region"],
    "link_resolvers": []
  },
  "rows": [{"data": {"Code": "A", "Region": "TW", "Qty": "2.00"}}]
}

此遷移範例要求欄位已存在且可寫入，並有一條 unique_tuple 規則依序宣告恰好 Code、Region。單欄鍵也可用 unique。符合的規則必須唯一；先透過一般規則 API 或 IaC 宣告。

模式效果
insert不帶 key_columns；新增所有通過驗證的列
upsert用 1–16 個已對應純量鍵欄比對；只更新已對應欄位，找不到才新增
update_only比對並更新；找不到鍵絕不新增

column_map 將來源名稱對應至可見、可寫的顯示名稱或內部鍵，兩個來源不能指向同一目標。鍵欄必須是已對應目標。遷移的比對與來源重複偵測採宣告規則的大小寫／Unicode／數字正規化。null／空白鍵、重複來源鍵或不明確的現存比對會拒絕整個圖。不可讀的比對會拒絕，不會因此新增重複資料或洩漏隱藏 ID。

擷取工作階段途徑若省略 key_policy，保留 #1840 的原始鍵比對。可在對應中設定 key_policy: "declared_unique"，改用與遷移相同的宣告鍵契約；不能視兩種策略為同義。

原生連結與巢狀子資料列

link_resolvers 項目為 {column, source_columns, target_columns}；兩組鍵各有 1–16 個不重複欄位，長度必須相等。目標只能來自目前原生連結定義，不是請求任選的目標表。需要目前目標表、列、欄位及 SCP 的讀取權限；採宣告鍵語意時，目標鍵也必須符合既有 unique／unique_tuple。純量及連結鍵來源仍受擷取途徑的精確 decimal 來源檢查。

JSON 遷移的子表定義放在請求層級：

{
  "key": "lines",
  "table_id": "33333333-3333-4333-8333-333333333333",
  "parent_link_column": "Header",
  "mapping": {"mode": "insert", "column_map": {"Qty": "Qty"}, "link_resolvers": []}
}

將定義放入請求 children 清單，每個主列的有序子列則放在 children.lines: [{data: {Qty: "2.00"}}]。Header 必須是同範圍內指向主表的單一原生連結。此欄由載入器設定，不能同時做純量對應或連結解析。請求內的子表 key 與 table ID 都不能重複。這只寫入一般子表資料列，不會設定子集合、刪除省略的子列、取代集合成員、重排既有列或產生群組修訂 manifest。

已儲存對應版本

PUT T/import-mappings/{name} 儲存 ImportMappingDefinition，GET 讀取，DELETE 停用名稱。名稱符合 [A-Za-z0-9_.-]{1,64}。儲存／刪除需目前表版主權限；讀取需表讀取權限，並重新驗證引用欄位與目標。

每次儲存建立不可變版本，每個名稱最多 64 版。回傳 {table_id, name, mapping, version}。可用 ?version=1 讀取，或執行時帶 mapping_name 與 mapping_version: 1；省略版本則用最新版。mapping 和 mapping_name 恰選一個，指定版本一定要有名稱。刪除也會停用歷史版本選擇；重新建立會遞增、不重用版號。settings.import_mappings 放最新定義，import_mapping_versions 保留版本紀錄，原生 IaC 會帶出兩者。對應不授權，也不凍結目標 schema；歷史版執行仍重新驗證目前 schema 與權限。

原子性與拒絕

先取得排序後的主表／引用鎖聯集，才取資料列鎖；在保護下重驗來源／工作階段、即時對應、schema 與權限。若新增鎖依賴，以 graph_changed 拒絕，不延伸鎖順序。原生動作依輸入順序執行，只提交一次，否則資料列、連結、序號配置及一般修訂全部回滾。目前期間、聚合、保留及 SCP 限制仍有效。commands_only 與需簽核的圖直接拒絕，不暫存、不排隊；匯入不是同意或 Command 豁免。

狀態範例／封套
400invalid_mapping、natural_key_not_declared、natural_key_rule_ambiguous、child_mapping_invalid；隱藏／未知／不相容欄位拒絕
403／404既有權限、租戶、來源工作階段及對應拒絕
409natural_key_missing、natural_key_ambiguous、duplicate_source_key、link_key_missing、link_key_ambiguous、graph_changed、approval_required、mapping_version_limit
422請求格式不符或 row_limit；detail 是陣列，不是一般匯入錯誤物件
423table_locked

一般匯入錯誤為 detail: {code, table_id?, source_index?}，只含固定錯誤碼與已授權識別，不含來源值、隱藏目標 ID 或 SQL 參數。寫入底線拒絕仍用自己的 detail.error 契約。

租戶匯出 bundle

GET /private/module/custom_tables/company/import-v2/bundle 需目前公司管理員權限，只匯出已驗證租戶的有效公司、部門與聊天室 CT 範圍。格式為 teamsync.ct.tenant-bundle.v1。include_records 預設 true；max_records 預設 200，可為 0–200，另受目前 IaC 資料列上限限制。

各範圍文件帶 scope、scope_id、table_ids、原生 jsonl、其 sha256、truncated_table_refs、dangling_target_ids、identity_diagnostics 與 principal_diagnostics。既有 IaC 位元組／行／表上限及機密遮罩仍適用。大型範圍拆為有界表切片；跨切片連結會列為懸空，不宣稱可獨立安裝。

只匯出 schema、截斷／懸空目標、不支援的列識別或不可攜 principal 都使 complete 為 false。bundle_identity_unsupported 只帶表 ref 與固定原因（key_column_missing、key_value_missing、key_value_unsupported、key_value_duplicate）。bundle_principal_unportable 只帶表 ref、principal 類型與數量。省略 reimport_company_id 代表需跨公司可攜性；只有已驗證公司的 ID 可採同公司重匯入假設。不重寫或自動對應 principal 值、JSONL 或綁定。

重匯入使用既有各範圍 IaC plan／apply，不是 blob 備份、principal 目錄、機密複製機制或自動跨範圍安裝器。端點卡見匯入參考，範圍準備見 IaC。

Last updated on
暫存世代與啟用併發與重試