Skip to Content
API 參考匯入資料

匯入資料

上傳來源檔案、預覽擷取結果,再建立新資料表或將資料列對應到既有資料表。

有界同步自然鍵 upsert/update-only、原生 link、子列、儲存 mapping 版本及租戶 bundle,請用匯入 v2。既有擷取/map/create 流程仍只新增。

POST
路由範本/private/module/custom_tables/{scope}/import/extract
用途

上傳 CSV、試算表、PDF 或其他支援的文件,並排程擷取其中可匯入的資料表候選內容。

適用時機

來源資料要轉成自訂資料表資料列時,先從這個端點開始。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/import/extract
  • 部門/private/module/custom_tables/department/{department_id}/import/extract
  • 公司/private/module/custom_tables/company/import/extract

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentTenantRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
workerqueryenum:legacy|batch|sqs|pubsub否執行擷取工作的背景執行器:legacy、batch、sqs 或 pubsub。省略時使用部署的 DEFAULT_BACKGROUND_WORKER_TYPE(未設定或無效時為 legacy)。
preserve_text_cellsqueryboolean否僅限 XLSX。設為 true 時會逐格讀取每個工作表,並精確保留作者輸入的文字,讓欄位之後能對應到 decimal;含有任何數字、日期或公式儲存格的欄位會被標為非文字,不能對應。每個工作表最多 100 欄、100,000 列,標題必須唯一且非空。

回應結構

TaskResponse
欄位型別必填說明
messagestring否未指定
ticket_idstring是Ticket ID

範例

上傳小型 CSV 並開始擷取

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "worker": "legacy"
  },
  "body": {
    "file": "<multipart file: orders.csv (text/csv)>"
  }
}
回應200
{
  "message": "Import extraction submitted",
  "ticket_id": "44444444-4444-8444-8444-444444444444"
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
400對副檔名不是 .xlsx 的檔案送出了 preserve_text_cells。請求在上傳前就被拒絕,不會排入任何工作。
{
  "detail": "preserve_text_cells supports .xlsx files only"
}
403此處的 403 body 來自 ChatRoomAccessRequired:聊天室建立者可通過,其他呼叫者在聊天室所屬部門需要部門管理員角色(否則即為此文字),來自其他部門則需要公司管理員角色(否則為 "Insufficient permissions, not at the same department. (Required company manager)");只是聊天室成員並不足夠;自後端 5.21.0 起,其他公司的聊天室與不存在的聊天室一樣回 404 "Chatroom Not found"。Company extraction 在未達 CAN_MANAGE_COMPANY 時回 "Insufficient permissions for company-level access."。Department extract/preview 依公司歸屬判斷,部門不存在或跨公司時回下方另列的 404。
{
  "detail": "Insufficient permissions, not the creator. (Required department manager)"
}
404僅 department scope:請求的部門不存在於呼叫者所屬公司。
{
  "detail": "Department not found"
}
413上傳檔案超過 CUSTOM_TABLE_IMPORT_MAX_BYTES;預設上限為 50 MiB。
{
  "detail": "File exceeds the maximum import size of 52428800 bytes"
}
500把工作提交給 batch、sqs 或 pubsub worker 時拋出錯誤(「Failed to submit task to AWS Batch: …」或「Failed to submit task to SQS-ECS: …」),ticket 會寫成 failed。在 create 分支上,新表格此時已經存在並維持空白。
{
  "detail": "Failed to submit task to SQS-ECS: <error>"
}
GET
路由範本/private/module/custom_tables/{scope}/import/{sid}

預覽匯入工作階段

用途

回傳偵測到的候選資料、來源欄位、推定型別、範例資料列與解析後的總筆數。

適用時機

擷取票證完成後,先用此端點確認內容,再決定建立新資料表或匯入既有資料表。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/import/{sid}
  • 部門/private/module/custom_tables/department/{department_id}/import/{sid}
  • 公司/private/module/custom_tables/company/import/{sid}

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentTenantRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
sidpathuuid是擷取工作完成後,以 import_session_id 回傳的匯入工作階段 UUID。

回應結構

ImportSessionPreview
欄位型別必填說明
candidatesImportCandidatePreview[]是未指定
filenamestring是未指定
fmtstring是未指定
sidstring是未指定

範例

檢視從 CSV 擷取的候選資料

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "sid": "33333333-3333-4333-8333-333333333333"
  }
}
回應200
{
  "sid": "33333333-3333-4333-8333-333333333333",
  "filename": "orders.csv",
  "fmt": "csv",
  "candidates": [
    {
      "signature": "a3f5f7d9b1c3e5f709182736455463728190aabbccddeeff0011223344556677",
      "source_columns": [
        {
          "name": "order_no",
          "sniffed_type": "string",
          "samples": [
            "A-1001"
          ]
        }
      ],
      "proposed_schema": [
        {
          "target_table_id": null,
          "cardinality": null,
          "link_field": null,
          "aggregation": null,
          "target_column": null,
          "direction": null,
          "source_table_id": null,
          "match": null,
          "filter": null,
          "expression": null,
          "pick": null,
          "fallback": null,
          "name": "order_no",
          "type": "string",
          "required": false,
          "default_value": null,
          "max_length": null,
          "description": null,
          "options": null,
          "max_count": null,
          "max_file_bytes": null,
          "allowed_mime_types": null
        }
      ],
      "sample_rows": [
        [
          "A-1001"
        ]
      ],
      "row_count": 1
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404僅 department scope:請求的部門不存在於呼叫者所屬公司。
{
  "detail": "Department not found"
}
404sid 不存在,或其 session 已過期:session 在擷取後保留 7,200 秒(2 小時)。
{
  "detail": "Import session not found or expired"
}
404Session 存在,但它是在其他 scope 類型或 scope id 中擷取的。Session 綁定於 scope,而不是使用者。
{
  "detail": "Import session not found in this scope"
}
POST
路由範本/private/module/custom_tables/{scope}/import/{sid}/create
用途

依編輯後的候選結構建立新資料表,按欄位順序完成對應,再排程寫入有效資料列。

適用時機

匯入資料應建立獨立資料表,而不是加入既有資料表時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/import/{sid}/create
  • 部門/private/module/custom_tables/department/{department_id}/import/{sid}/create
  • 公司/private/module/custom_tables/company/import/{sid}/create

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
sidpathuuid是包含所選候選資料的匯入工作階段 UUID。
workerqueryenum:legacy|batch|sqs|pubsub否執行資料列寫入工作的背景執行器:legacy、batch、sqs 或 pubsub。預設為部署的 DEFAULT_BACKGROUND_WORKER_TYPE(未設定或無效時為 legacy)。

請求結構

ImportCreatePayload
欄位型別必填說明
descriptionstring | null否未指定
schema_definitionTableSchema是Final schema to create; explicitly selecting Boolean converts imported true/false text at commit (case-insensitive, surrounding whitespace allowed)
signaturestring是Candidate signature from the preview
skip_invalidboolean否Skip mapper-required failures; worker type errors remain indexed per row and may leave valid rows inserted
table_namestring是Name for the new table

範例

建立訂單資料表並排程寫入資料列

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "sid": "33333333-3333-4333-8333-333333333333"
  },
  "query": {
    "worker": "legacy"
  },
  "body": {
    "signature": "a3f5f7d9b1c3e5f709182736455463728190aabbccddeeff0011223344556677",
    "table_name": "Imported orders",
    "description": "Orders loaded from CSV",
    "schema_definition": {
      "columns": [
        {
          "name": "Order number",
          "type": "string",
          "required": true
        }
      ]
    },
    "skip_invalid": true
  }
}
回應201
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "ticket_id": "ct-bulk-55555555-5555-4555-8555-555555555555",
  "message": "Table created; rows inserting"
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
400簽章不是此 session 的候選,或其儲存的資料列不存在(「Candidate rows not found for signature」)。下方其他 400 各有自己的列。
{
  "detail": "Candidate signature not found in this session"
}
400decimal 目標讀取的 .xlsx 來源不是以 preserve_text_cells=true 擷取,或該欄含有原生數字、日期或公式儲存格,或編輯後的 decimal schema 沒有保持來源欄數。這些都在建立表格之前檢查。
{
  "detail": "Decimal XLSX import requires re-extraction with preserve_text_cells=true"
}
400來源為舊式 .xls(BIFF),且映射或新宣告的目標是 decimal。擷取可能已將儲存格四捨五入;請用 UTF-8 CSV 或以 preserve_text_cells=true 擷取的 XLSX 文字儲存格。建表或寫列之前即拒絕。
{
  "detail": "Decimal XLS import is unsupported because extraction may round cells; use UTF-8 CSV or text cells in XLSX with preserve_text_cells=true"
}
400編輯後的 schema 沒有保持候選的欄數。在建立表格之前檢查。含 decimal 欄位時,較早的檢查會改回「Edited decimal import schema must match the source column count」。
{
  "detail": "Edited schema must have the same number of columns, in the same order, as the candidate (renaming and retyping are allowed; adding/removing columns is not supported in v1)."
}
400編輯後的 schema 含有 link、rollup、lookup 或 formula 欄位。在建立表格之前檢查;這類欄位請在匯入後新增。
{
  "detail": "link/rollup/lookup/formula columns cannot be created via import; create the table first, then add them via the column endpoint"
}
400編輯後的 schema 含有 json 欄位,匯入的文字只會存成一般字串。在建立表格之前檢查。
{
  "detail": "json columns cannot be created via import; create the table first, then add them via the column endpoint"
}
400skip_invalid=true 因缺少 required 值而丟掉了每一列。表格已經建立並維持空白。
{
  "detail": "No valid rows to insert after mapping"
}
404sid 不存在,或其 session 已過期:session 在擷取後保留 7,200 秒(2 小時)。
{
  "detail": "Import session not found or expired"
}
404Session 存在,但它是在其他 scope 類型或 scope id 中擷取的。Session 綁定於 scope,而不是使用者。
{
  "detail": "Import session not found in this scope"
}
409工作階段仍存在,但保存的來源資料列已過期。
{
  "detail": "Import data expired; re-extract the file"
}
422skip_invalid=false 且某一列缺少 required 值;error 會指出 zero-based 列號與內部欄位 id。表格已經建立並維持空白。
{
  "detail": {
    "table_id": "22222222-2222-4222-8222-222222222222",
    "error": "row 3: missing required column(s) ['col_a1111111_1111_4111_8111_111111111111']",
    "note": "Table was created but rows failed validation; fix data or use skip_invalid=true"
  }
}
422對應後仍超過 50,000 筆紀錄。表格已建立且維持空白;請拆分檔案。
{
  "detail": {
    "table_id": "22222222-2222-4222-8222-222222222222",
    "error": "Import has more than 50000 mapped records in one bulk insert",
    "note": "Table was created but no import rows were submitted"
  }
}
500把工作提交給 batch、sqs 或 pubsub worker 時拋出錯誤(「Failed to submit task to AWS Batch: …」或「Failed to submit task to SQS-ECS: …」),ticket 會寫成 failed。在 create 分支上,新表格此時已經存在並維持空白。
{
  "detail": "Failed to submit task to SQS-ECS: <error>"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/import/{sid}
用途

把來源欄位解析成既有資料表中可寫入的一般欄位,並排程寫入對應後的資料列。

適用時機

目的資料表已存在,且要保留目前結構時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/import/{sid}
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/import/{sid}
  • 公司/private/module/custom_tables/company/tables/{table_id}/import/{sid}

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableInsertRequired
部門可使用CustomTableInsertRequired
公司可使用CustomTableInsertRequired

參數

欄位位置型別必填說明
table_idpathuuid是既有目的資料表的 UUID。
sidpathuuid是包含所選候選資料的匯入工作階段 UUID。
workerqueryenum:legacy|batch|sqs|pubsub否執行資料列寫入工作的背景執行器:legacy、batch、sqs 或 pubsub。預設為部署的 DEFAULT_BACKGROUND_WORKER_TYPE(未設定或無效時為 legacy)。

請求結構

ImportMapPayload
欄位型別必填說明
column_mapRecord<string, string>是Map of {source_column_name: target_column_display_name}. Target names are resolved to internal IDs via the table's column_mapping. If a source name repeats, its last occurrence supplies the mapped value; unused duplicates do not block extraction or other mappings. Boolean targets convert only true/false source text at commit (case-insensitive, surrounding whitespace allowed).
signaturestring是Candidate signature from the preview
skip_invalidboolean否Skip mapper-required failures; worker type errors remain indexed per row and may leave valid rows inserted

回應結構

TaskResponse
欄位型別必填說明
messagestring否未指定
ticket_idstring是Ticket ID

範例

將 CSV 欄位對應到既有訂單資料表

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "sid": "33333333-3333-4333-8333-333333333333"
  },
  "query": {
    "worker": "legacy"
  },
  "body": {
    "signature": "a3f5f7d9b1c3e5f709182736455463728190aabbccddeeff0011223344556677",
    "column_map": {
      "order_no": "Order number"
    },
    "skip_invalid": true
  }
}
回應200
{
  "message": "Bulk insert task submitted",
  "ticket_id": "ct-bulk-55555555-5555-4555-8555-555555555555"
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403資料表的 `write_policy` 是 `commands_only`:任何不在 Command 之內的主體所做的資料列寫入,都會在任何東西被暫存、排入佇列或 commit 之前,以 typed 的 `governed_context_required` 被拒絕(不會產生版本、history、receipt、token 或 Review process)。`operation` 指出是哪種寫入,若該通道有名稱則以 `surface` 指出;請改用被允許寫入該資料表的 Command。讀取不受影響。
{
  "detail": {
    "error": "governed_context_required",
    "message": "This table accepts record writes only through Commands (write_policy: commands_only). Run a Command that is allowed to write it instead.",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "operation": "create",
    "surface": "bulk_insert"
  }
}
400目的欄位不存在或對呼叫者隱藏;兩者回相同文字,因此無法探測隱藏欄位。建立新表卡片上的簽章錯誤在這裡同樣適用。
{
  "detail": "Unknown target column 'Missing column'"
}
400對應的目標是 json 欄位(「Column '<target>' is a json column and cannot be an import target」)或 computed 欄位(「Column '<target>' is a <type> column and cannot be an import target」)。
{
  "detail": "Column 'Notes' is a json column and cannot be an import target"
}
400decimal 目標欄的來源是 .xlsx,但其 session 沒有 preserve_text_cells=true,或來源欄含有非文字儲存格,因此其值可能已被捨入。
{
  "detail": "Decimal XLSX import requires text-formatted source cells; native numeric cells may already be rounded"
}
400來源為舊式 .xls(BIFF),且映射或新宣告的目標是 decimal。擷取可能已將儲存格四捨五入;請用 UTF-8 CSV 或以 preserve_text_cells=true 擷取的 XLSX 文字儲存格。建表或寫列之前即拒絕。
{
  "detail": "Decimal XLS import is unsupported because extraction may round cells; use UTF-8 CSV or text cells in XLSX with preserve_text_cells=true"
}
400skip_invalid=true 時沒有任何一列通過 required 值檢查。未對應的 required 欄位會讓每一列失敗,即使該欄有預設值也一樣。
{
  "detail": "No valid rows to insert after mapping"
}
400對應後仍超過 50,000 筆紀錄,超出 bulk-insert 上限。不會派送任何工作;請拆分檔案。
{
  "detail": "Import has more than 50000 mapped records in one bulk insert"
}
403呼叫者沒有在目的資料表新增資料列的權限。
{
  "detail": "Insert access not granted for this table."
}
404指定範圍內找不到目的資料表。
{
  "detail": "Table not found in this chatroom"
}
404sid 不存在,或其 session 已過期:session 在擷取後保留 7,200 秒(2 小時)。
{
  "detail": "Import session not found or expired"
}
404Session 存在,但它是在其他 scope 類型或 scope id 中擷取的。Session 綁定於 scope,而不是使用者。
{
  "detail": "Import session not found in this scope"
}
409Session 存在,但它儲存的資料列已不存在(「Import data expired; re-extract the file」或「Import session has no stored rows; re-extract」)。請重新擷取檔案。
{
  "detail": "Import data expired; re-extract the file"
}
422skip_invalid=false 且某一列缺少 required 值:detail 會指出 zero-based 列號與內部欄位 id。沒有派送任何工作。
{
  "detail": "row 3: missing required column(s) ['col_a1111111_1111_4111_8111_111111111111']"
}
423Migration 正持有目標表格的鎖。沒有派送任何工作。
{
  "detail": "Table is currently locked for operation: add_column"
}
500把工作提交給 batch、sqs 或 pubsub worker 時拋出錯誤(「Failed to submit task to AWS Batch: …」或「Failed to submit task to SQS-ECS: …」),ticket 會寫成 failed。在 create 分支上,新表格此時已經存在並維持空白。
{
  "detail": "Failed to submit task to SQS-ECS: <error>"
}
POST
路由範本/private/module/custom_tables/{importScope}/tables/{table_id}/import-v2/{sid}
用途

以內嵌或已儲存 mapping 處理純量、連結與子資料列,在同一原生交易完成。

適用時機

使用 insert、upsert 或 update_only,不走 v1 背景派送。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{scope_id}/tables/{table_id}/import-v2/{sid}
  • 部門/private/module/custom_tables/department/{scope_id}/tables/{table_id}/import-v2/{sid}
  • 公司/private/module/custom_tables/company/tables/{table_id}/import-v2/{sid}

範圍

範圍是否提供驗證與權限
聊天室可使用authorize_import_table(access=write)
部門可使用authorize_import_table(access=write)
公司可使用authorize_import_table(access=write)

參數

欄位位置型別必填說明
table_idpathuuid是此範圍中目前資料表的 UUID。
sidpathuuid是仍有效的擷取 session UUID;使用候選資料實際的 signature。

請求結構

ImportV2Request
欄位型別必填說明
childrenImportChildSelection[]否未指定
mappingImportMappingDefinition | null否未指定
mapping_namestring | null否未指定
mapping_versioninteger | null否未指定
signaturestring是未指定

回應結構

ImportV2Response
欄位型別必填說明
insertedinteger是未指定
rowsImportRowReceipt[]是未指定
updatedinteger是未指定

範例

以已宣告唯一的 Code 鍵 upsert Code/Amount

請求
{
  "pathParams": {
    "scope_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "sid": "33333333-3333-4333-8333-333333333333",
    "name": "orders"
  },
  "body": {
    "signature": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "mapping": {
      "mode": "upsert",
      "column_map": {
        "Code": "Code",
        "Amount": "Amount"
      },
      "key_columns": [
        "Code"
      ],
      "key_policy": "declared_unique",
      "link_resolvers": []
    }
  }
}
回應200
{
  "inserted": 1,
  "updated": 0,
  "rows": [
    {
      "table_id": "22222222-2222-4222-8222-222222222222",
      "record_id": "44444444-4444-4444-8444-444444444444",
      "source_index": 0,
      "disposition": "insert"
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
400鍵 mapping 不符合順序完全一致的已宣告 unique/unique_tuple;不會寫入。
{
  "detail": {
    "code": "natural_key_not_declared",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
409找不到來源自然鍵;模糊/重複鍵、資料圖變更與審批門檻也會原子拒絕。
{
  "detail": {
    "code": "natural_key_missing",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "source_index": 0
  }
}
423資料圖中的表已鎖定,不會部分匯入。
{
  "detail": {
    "code": "table_locked",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
POST
路由範本/private/module/custom_tables/{importScope}/tables/{table_id}/import-v2/migration
用途

依已宣告唯一鍵比對,在有上限的同範圍資料圖解析原生連結。

適用時機

整合結構化資料,使用精確宣告鍵正規化與逐來源列收據。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{scope_id}/tables/{table_id}/import-v2/migration
  • 部門/private/module/custom_tables/department/{scope_id}/tables/{table_id}/import-v2/migration
  • 公司/private/module/custom_tables/company/tables/{table_id}/import-v2/migration

範圍

範圍是否提供驗證與權限
聊天室可使用authorize_import_table(access=write)
部門可使用authorize_import_table(access=write)
公司可使用authorize_import_table(access=write)

參數

欄位位置型別必填說明
table_idpathuuid是此範圍中目前資料表的 UUID。

請求結構

ImportMigrationRequest
欄位型別必填說明
childrenImportMigrationChildDefinition[]否未指定
mappingImportMappingDefinition | null否未指定
mapping_namestring | null否未指定
mapping_versioninteger | null否未指定
rowsImportMigrationRow[]是未指定

回應結構

ImportV2Response
欄位型別必填說明
insertedinteger是未指定
rowsImportRowReceipt[]是未指定
updatedinteger是未指定

範例

依已宣告唯一的 Code 鍵載入一筆主資料

請求
{
  "pathParams": {
    "scope_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "sid": "33333333-3333-4333-8333-333333333333",
    "name": "orders"
  },
  "body": {
    "mapping": {
      "mode": "upsert",
      "column_map": {
        "Code": "Code",
        "Amount": "Amount"
      },
      "key_columns": [
        "Code"
      ],
      "key_policy": "declared_unique",
      "link_resolvers": []
    },
    "rows": [
      {
        "data": {
          "Code": "A",
          "Amount": "12.00"
        }
      }
    ]
  }
}
回應200
{
  "inserted": 1,
  "updated": 0,
  "rows": [
    {
      "table_id": "22222222-2222-4222-8222-222222222222",
      "record_id": "44444444-4444-4444-8444-444444444444",
      "source_index": 0,
      "disposition": "insert"
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
400鍵 mapping 不符合順序完全一致的已宣告 unique/unique_tuple;不會寫入。
{
  "detail": {
    "code": "natural_key_not_declared",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
409找不到來源自然鍵;模糊/重複鍵、資料圖變更與審批門檻也會原子拒絕。
{
  "detail": {
    "code": "natural_key_missing",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "source_index": 0
  }
}
423資料圖中的表已鎖定,不會部分匯入。
{
  "detail": {
    "code": "table_locked",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
PUT
路由範本/private/module/custom_tables/{importScope}/tables/{table_id}/import-mappings/{name}
用途

驗證並儲存 moderator 定義的 mapping,不匯入資料列。

適用時機

重用 mapping,同時固定確切版本。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{scope_id}/tables/{table_id}/import-mappings/{name}
  • 部門/private/module/custom_tables/department/{scope_id}/tables/{table_id}/import-mappings/{name}
  • 公司/private/module/custom_tables/company/tables/{table_id}/import-mappings/{name}

範圍

範圍是否提供驗證與權限
聊天室可使用authorize_import_table(access=moderator)
部門可使用authorize_import_table(access=moderator)
公司可使用authorize_import_table(access=moderator)

參數

欄位位置型別必填說明
table_idpathuuid是此範圍中目前資料表的 UUID。
namepathstring是符合 [A-Za-z0-9_.-]{1,64} 的 mapping 名稱。

請求結構

ImportMappingDefinition
欄位型別必填說明
column_mapRecord<string, string>是未指定
key_columnsstring[]否未指定
key_policystring | null否未指定
link_resolversImportLinkResolver[]否未指定
mode"insert" | "upsert" | "update_only"是未指定

回應結構

ImportMappingResponse
欄位型別必填說明
mappingImportMappingDefinition是未指定
namestring是未指定
table_idstring (uuid)是未指定
versioninteger是未指定

範例

儲存 orders 第 1 版

請求
{
  "pathParams": {
    "scope_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "sid": "33333333-3333-4333-8333-333333333333",
    "name": "orders"
  },
  "body": {
    "mode": "upsert",
    "column_map": {
      "Code": "Code",
      "Amount": "Amount"
    },
    "key_columns": [
      "Code"
    ],
    "key_policy": "declared_unique",
    "link_resolvers": []
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "name": "orders",
  "mapping": {
    "mode": "upsert",
    "column_map": {
      "Code": "Code",
      "Amount": "Amount"
    },
    "key_columns": [
      "Code"
    ],
    "key_policy": "declared_unique",
    "link_resolvers": []
  },
  "version": 1
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
409此名稱已達 64 個不可變版本。
{
  "detail": {
    "code": "mapping_version_limit",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
400參照欄位或原生連結 mapping 不可用或不相容。
{
  "detail": {
    "code": "invalid_mapping",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
GET
路由範本/private/module/custom_tables/{importScope}/tables/{table_id}/import-mappings/{name}
用途

讀最新版或指定定義,重新驗證目前參照。

適用時機

載入前檢視 mapping。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{scope_id}/tables/{table_id}/import-mappings/{name}
  • 部門/private/module/custom_tables/department/{scope_id}/tables/{table_id}/import-mappings/{name}
  • 公司/private/module/custom_tables/company/tables/{table_id}/import-mappings/{name}

範圍

範圍是否提供驗證與權限
聊天室可使用authorize_import_table(access=read)
部門可使用authorize_import_table(access=read)
公司可使用authorize_import_table(access=read)

參數

欄位位置型別必填說明
table_idpathuuid是此範圍中目前資料表的 UUID。
namepathstring是符合 [A-Za-z0-9_.-]{1,64} 的 mapping 名稱。
versionqueryint:1..64否不可變版本 1–64;省略則讀最新版。

回應結構

ImportMappingResponse
欄位型別必填說明
mappingImportMappingDefinition是未指定
namestring是未指定
table_idstring (uuid)是未指定
versioninteger是未指定

範例

讀取第一個已儲存版本

請求
{
  "pathParams": {
    "scope_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "sid": "33333333-3333-4333-8333-333333333333",
    "name": "orders"
  },
  "query": {
    "version": "1"
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "name": "orders",
  "mapping": {
    "mode": "upsert",
    "column_map": {
      "Code": "Code",
      "Amount": "Amount"
    },
    "key_columns": [
      "Code"
    ],
    "key_policy": "declared_unique",
    "link_resolvers": []
  },
  "version": 1
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404Mapping 不存在/已停用;指定版本不可用則為 mapping_version_not_found。
{
  "detail": {
    "code": "mapping_not_found",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
400參照欄位或原生連結 mapping 不可用或不相容。
{
  "detail": {
    "code": "invalid_mapping",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
DELETE
路由範本/private/module/custom_tables/{importScope}/tables/{table_id}/import-mappings/{name}
用途

在 settings lock 內移除啟用名稱,也停用歷史版本選取。

適用時機

停用 mapping,不變更其他設定。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{scope_id}/tables/{table_id}/import-mappings/{name}
  • 部門/private/module/custom_tables/department/{scope_id}/tables/{table_id}/import-mappings/{name}
  • 公司/private/module/custom_tables/company/tables/{table_id}/import-mappings/{name}

範圍

範圍是否提供驗證與權限
聊天室可使用authorize_import_table(access=moderator)
部門可使用authorize_import_table(access=moderator)
公司可使用authorize_import_table(access=moderator)

參數

欄位位置型別必填說明
table_idpathuuid是此範圍中目前資料表的 UUID。
namepathstring是符合 [A-Za-z0-9_.-]{1,64} 的 mapping 名稱。

回應結構

ImportMappingDeleteResponse
欄位型別必填說明
deletedboolean否未指定
namestring是未指定
table_idstring (uuid)是未指定

範例

停用 orders 與其歷史版本選取

請求
{
  "pathParams": {
    "scope_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "sid": "33333333-3333-4333-8333-333333333333",
    "name": "orders"
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "name": "orders",
  "deleted": true
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404Mapping 不存在/已停用;指定版本不可用則為 mapping_version_not_found。
{
  "detail": {
    "code": "mapping_not_found",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
GET
路由範本/private/module/custom_tables/company/import-v2/bundle
用途

將此租戶各 CT 範圍的有效資料表匯成原生 IaC 切片,附 digest 與可攜性診斷。

適用時機

準備按範圍重匯 IaC;先檢查 complete 與每項診斷。

實際掛載路徑
  • 完整路由/private/module/custom_tables/company/import-v2/bundle

範圍

範圍是否提供驗證與權限
完整路由可使用CompanyAccessRequired (company manager)

參數

欄位位置型別必填說明
include_recordsqueryboolean否包含有上限的原生 IaC 種子;預設 true。
max_recordsqueryint:0..200否每表 0–200 筆種子,預設 200;仍受目前 IaC 上限限制。
reimport_company_idqueryuuid否僅目前登入公司的 UUID 啟用同公司假設;跨公司可攜性檢查請省略。

回應結構

ImportTenantBundle
欄位型別必填說明
company_idstring (uuid)是未指定
completeboolean是未指定
formatstring否未指定
include_recordsboolean是未指定
reimport_company_idstring (uuid) | null否未指定
scopesImportBundleScope[]是未指定

範例

空租戶(各範圍都沒有有效資料表)

請求
{
  "pathParams": {},
  "query": {
    "include_records": "true",
    "max_records": "200"
  }
}
回應200
{
  "format": "teamsync.ct.tenant-bundle.v1",
  "company_id": "55555555-5555-4555-8555-555555555555",
  "include_records": true,
  "complete": true,
  "scopes": []
}

錯誤

驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
409某個範圍切片無法符合原生 IaC 契約而匯出。
{
  "detail": {
    "code": "export_refused"
  }
}
Last updated on