匯入資料
上傳來源檔案、預覽擷取結果,再建立新資料表或將資料列對應到既有資料表。
有界同步自然鍵 upsert/update-only、原生 link、子列、儲存 mapping 版本及租戶 bundle,請用匯入 v2。既有擷取/map/create 流程仍只新增。
/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 |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
worker | query | enum:legacy|batch|sqs|pubsub | 否 | 執行擷取工作的背景執行器:legacy、batch、sqs 或 pubsub。省略時使用部署的 DEFAULT_BACKGROUND_WORKER_TYPE(未設定或無效時為 legacy)。 |
preserve_text_cells | query | boolean | 否 | 僅限 XLSX。設為 true 時會逐格讀取每個工作表,並精確保留作者輸入的文字,讓欄位之後能對應到 decimal;含有任何數字、日期或公式儲存格的欄位會被標為非文字,不能對應。每個工作表最多 100 欄、100,000 列,標題必須唯一且非空。 |
回應結構
TaskResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
message | string | 否 | 未指定 |
ticket_id | string | 是 | Ticket ID |
範例
上傳小型 CSV 並開始擷取
{
"pathParams": {
"chatroom_id": "11111111-1111-4111-8111-111111111111"
},
"query": {
"worker": "legacy"
},
"body": {
"file": "<multipart file: orders.csv (text/csv)>"
}
}{
"message": "Import extraction submitted",
"ticket_id": "44444444-4444-8444-8444-444444444444"
}錯誤
驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。
| 狀態 | 發生條件 | 錯誤本文 |
|---|---|---|
| 400 | 對副檔名不是 .xlsx 的檔案送出了 preserve_text_cells。請求在上傳前就被拒絕,不會排入任何工作。 | |
| 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。 | |
| 404 | 僅 department scope:請求的部門不存在於呼叫者所屬公司。 | |
| 413 | 上傳檔案超過 CUSTOM_TABLE_IMPORT_MAX_BYTES;預設上限為 50 MiB。 | |
| 500 | 把工作提交給 batch、sqs 或 pubsub worker 時拋出錯誤(「Failed to submit task to AWS Batch: …」或「Failed to submit task to SQS-ECS: …」),ticket 會寫成 failed。在 create 分支上,新表格此時已經存在並維持空白。 | |
/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 |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
sid | path | uuid | 是 | 擷取工作完成後,以 import_session_id 回傳的匯入工作階段 UUID。 |
回應結構
ImportSessionPreview| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
candidates | ImportCandidatePreview[] | 是 | 未指定 |
filename | string | 是 | 未指定 |
fmt | string | 是 | 未指定 |
sid | string | 是 | 未指定 |
範例
檢視從 CSV 擷取的候選資料
{
"pathParams": {
"chatroom_id": "11111111-1111-4111-8111-111111111111",
"sid": "33333333-3333-4333-8333-333333333333"
}
}{
"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:請求的部門不存在於呼叫者所屬公司。 | |
| 404 | sid 不存在,或其 session 已過期:session 在擷取後保留 7,200 秒(2 小時)。 | |
| 404 | Session 存在,但它是在其他 scope 類型或 scope id 中擷取的。Session 綁定於 scope,而不是使用者。 | |
/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 |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
sid | path | uuid | 是 | 包含所選候選資料的匯入工作階段 UUID。 |
worker | query | enum:legacy|batch|sqs|pubsub | 否 | 執行資料列寫入工作的背景執行器:legacy、batch、sqs 或 pubsub。預設為部署的 DEFAULT_BACKGROUND_WORKER_TYPE(未設定或無效時為 legacy)。 |
請求結構
ImportCreatePayload| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
description | string | null | 否 | 未指定 |
schema_definition | TableSchema | 是 | Final schema to create; explicitly selecting Boolean converts imported true/false text at commit (case-insensitive, surrounding whitespace allowed) |
signature | string | 是 | Candidate signature from the preview |
skip_invalid | boolean | 否 | Skip mapper-required failures; worker type errors remain indexed per row and may leave valid rows inserted |
table_name | string | 是 | 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
}
}{
"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 各有自己的列。 | |
| 400 | decimal 目標讀取的 .xlsx 來源不是以 preserve_text_cells=true 擷取,或該欄含有原生數字、日期或公式儲存格,或編輯後的 decimal schema 沒有保持來源欄數。這些都在建立表格之前檢查。 | |
| 400 | 來源為舊式 .xls(BIFF),且映射或新宣告的目標是 decimal。擷取可能已將儲存格四捨五入;請用 UTF-8 CSV 或以 preserve_text_cells=true 擷取的 XLSX 文字儲存格。建表或寫列之前即拒絕。 | |
| 400 | 編輯後的 schema 沒有保持候選的欄數。在建立表格之前檢查。含 decimal 欄位時,較早的檢查會改回「Edited decimal import schema must match the source column count」。 | |
| 400 | 編輯後的 schema 含有 link、rollup、lookup 或 formula 欄位。在建立表格之前檢查;這類欄位請在匯入後新增。 | |
| 400 | 編輯後的 schema 含有 json 欄位,匯入的文字只會存成一般字串。在建立表格之前檢查。 | |
| 400 | skip_invalid=true 因缺少 required 值而丟掉了每一列。表格已經建立並維持空白。 | |
| 404 | sid 不存在,或其 session 已過期:session 在擷取後保留 7,200 秒(2 小時)。 | |
| 404 | Session 存在,但它是在其他 scope 類型或 scope id 中擷取的。Session 綁定於 scope,而不是使用者。 | |
| 409 | 工作階段仍存在,但保存的來源資料列已過期。 | |
| 422 | skip_invalid=false 且某一列缺少 required 值;error 會指出 zero-based 列號與內部欄位 id。表格已經建立並維持空白。 | |
| 422 | 對應後仍超過 50,000 筆紀錄。表格已建立且維持空白;請拆分檔案。 | |
| 500 | 把工作提交給 batch、sqs 或 pubsub worker 時拋出錯誤(「Failed to submit task to AWS Batch: …」或「Failed to submit task to SQS-ECS: …」),ticket 會寫成 failed。在 create 分支上,新表格此時已經存在並維持空白。 | |
/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_id | path | uuid | 是 | 既有目的資料表的 UUID。 |
sid | path | uuid | 是 | 包含所選候選資料的匯入工作階段 UUID。 |
worker | query | enum:legacy|batch|sqs|pubsub | 否 | 執行資料列寫入工作的背景執行器:legacy、batch、sqs 或 pubsub。預設為部署的 DEFAULT_BACKGROUND_WORKER_TYPE(未設定或無效時為 legacy)。 |
請求結構
ImportMapPayload| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
column_map | Record<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). |
signature | string | 是 | Candidate signature from the preview |
skip_invalid | boolean | 否 | Skip mapper-required failures; worker type errors remain indexed per row and may leave valid rows inserted |
回應結構
TaskResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
message | string | 否 | 未指定 |
ticket_id | string | 是 | 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
}
}{
"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。讀取不受影響。 | |
| 400 | 目的欄位不存在或對呼叫者隱藏;兩者回相同文字,因此無法探測隱藏欄位。建立新表卡片上的簽章錯誤在這裡同樣適用。 | |
| 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」)。 | |
| 400 | decimal 目標欄的來源是 .xlsx,但其 session 沒有 preserve_text_cells=true,或來源欄含有非文字儲存格,因此其值可能已被捨入。 | |
| 400 | 來源為舊式 .xls(BIFF),且映射或新宣告的目標是 decimal。擷取可能已將儲存格四捨五入;請用 UTF-8 CSV 或以 preserve_text_cells=true 擷取的 XLSX 文字儲存格。建表或寫列之前即拒絕。 | |
| 400 | skip_invalid=true 時沒有任何一列通過 required 值檢查。未對應的 required 欄位會讓每一列失敗,即使該欄有預設值也一樣。 | |
| 400 | 對應後仍超過 50,000 筆紀錄,超出 bulk-insert 上限。不會派送任何工作;請拆分檔案。 | |
| 403 | 呼叫者沒有在目的資料表新增資料列的權限。 | |
| 404 | 指定範圍內找不到目的資料表。 | |
| 404 | sid 不存在,或其 session 已過期:session 在擷取後保留 7,200 秒(2 小時)。 | |
| 404 | Session 存在,但它是在其他 scope 類型或 scope id 中擷取的。Session 綁定於 scope,而不是使用者。 | |
| 409 | Session 存在,但它儲存的資料列已不存在(「Import data expired; re-extract the file」或「Import session has no stored rows; re-extract」)。請重新擷取檔案。 | |
| 422 | skip_invalid=false 且某一列缺少 required 值:detail 會指出 zero-based 列號與內部欄位 id。沒有派送任何工作。 | |
| 423 | Migration 正持有目標表格的鎖。沒有派送任何工作。 | |
| 500 | 把工作提交給 batch、sqs 或 pubsub worker 時拋出錯誤(「Failed to submit task to AWS Batch: …」或「Failed to submit task to SQS-ECS: …」),ticket 會寫成 failed。在 create 分支上,新表格此時已經存在並維持空白。 | |
/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_id | path | uuid | 是 | 此範圍中目前資料表的 UUID。 |
sid | path | uuid | 是 | 仍有效的擷取 session UUID;使用候選資料實際的 signature。 |
請求結構
ImportV2Request| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
children | ImportChildSelection[] | 否 | 未指定 |
mapping | ImportMappingDefinition | null | 否 | 未指定 |
mapping_name | string | null | 否 | 未指定 |
mapping_version | integer | null | 否 | 未指定 |
signature | string | 是 | 未指定 |
回應結構
ImportV2Response| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
inserted | integer | 是 | 未指定 |
rows | ImportRowReceipt[] | 是 | 未指定 |
updated | integer | 是 | 未指定 |
範例
以已宣告唯一的 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": []
}
}
}{
"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;不會寫入。 | |
| 409 | 找不到來源自然鍵;模糊/重複鍵、資料圖變更與審批門檻也會原子拒絕。 | |
| 423 | 資料圖中的表已鎖定,不會部分匯入。 | |
/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_id | path | uuid | 是 | 此範圍中目前資料表的 UUID。 |
請求結構
ImportMigrationRequest| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
children | ImportMigrationChildDefinition[] | 否 | 未指定 |
mapping | ImportMappingDefinition | null | 否 | 未指定 |
mapping_name | string | null | 否 | 未指定 |
mapping_version | integer | null | 否 | 未指定 |
rows | ImportMigrationRow[] | 是 | 未指定 |
回應結構
ImportV2Response| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
inserted | integer | 是 | 未指定 |
rows | ImportRowReceipt[] | 是 | 未指定 |
updated | integer | 是 | 未指定 |
範例
依已宣告唯一的 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"
}
}
]
}
}{
"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;不會寫入。 | |
| 409 | 找不到來源自然鍵;模糊/重複鍵、資料圖變更與審批門檻也會原子拒絕。 | |
| 423 | 資料圖中的表已鎖定,不會部分匯入。 | |
/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_id | path | uuid | 是 | 此範圍中目前資料表的 UUID。 |
name | path | string | 是 | 符合 [A-Za-z0-9_.-]{1,64} 的 mapping 名稱。 |
請求結構
ImportMappingDefinition| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
column_map | Record<string, string> | 是 | 未指定 |
key_columns | string[] | 否 | 未指定 |
key_policy | string | null | 否 | 未指定 |
link_resolvers | ImportLinkResolver[] | 否 | 未指定 |
mode | "insert" | "upsert" | "update_only" | 是 | 未指定 |
回應結構
ImportMappingResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
mapping | ImportMappingDefinition | 是 | 未指定 |
name | string | 是 | 未指定 |
table_id | string (uuid) | 是 | 未指定 |
version | integer | 是 | 未指定 |
範例
儲存 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": []
}
}{
"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 個不可變版本。 | |
| 400 | 參照欄位或原生連結 mapping 不可用或不相容。 | |
/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_id | path | uuid | 是 | 此範圍中目前資料表的 UUID。 |
name | path | string | 是 | 符合 [A-Za-z0-9_.-]{1,64} 的 mapping 名稱。 |
version | query | int:1..64 | 否 | 不可變版本 1–64;省略則讀最新版。 |
回應結構
ImportMappingResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
mapping | ImportMappingDefinition | 是 | 未指定 |
name | string | 是 | 未指定 |
table_id | string (uuid) | 是 | 未指定 |
version | integer | 是 | 未指定 |
範例
讀取第一個已儲存版本
{
"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"
}
}{
"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 佔位符。
| 狀態 | 發生條件 | 錯誤本文 |
|---|---|---|
| 404 | Mapping 不存在/已停用;指定版本不可用則為 mapping_version_not_found。 | |
| 400 | 參照欄位或原生連結 mapping 不可用或不相容。 | |
/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_id | path | uuid | 是 | 此範圍中目前資料表的 UUID。 |
name | path | string | 是 | 符合 [A-Za-z0-9_.-]{1,64} 的 mapping 名稱。 |
回應結構
ImportMappingDeleteResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
deleted | boolean | 否 | 未指定 |
name | string | 是 | 未指定 |
table_id | string (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"
}
}{
"table_id": "22222222-2222-4222-8222-222222222222",
"name": "orders",
"deleted": true
}錯誤
驗證錯誤範例列出識別欄位;部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定,因此使用 pydantic-version 佔位符。
| 狀態 | 發生條件 | 錯誤本文 |
|---|---|---|
| 404 | Mapping 不存在/已停用;指定版本不可用則為 mapping_version_not_found。 | |
/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_records | query | boolean | 否 | 包含有上限的原生 IaC 種子;預設 true。 |
max_records | query | int:0..200 | 否 | 每表 0–200 筆種子,預設 200;仍受目前 IaC 上限限制。 |
reimport_company_id | query | uuid | 否 | 僅目前登入公司的 UUID 啟用同公司假設;跨公司可攜性檢查請省略。 |
回應結構
ImportTenantBundle| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
company_id | string (uuid) | 是 | 未指定 |
complete | boolean | 是 | 未指定 |
format | string | 否 | 未指定 |
include_records | boolean | 是 | 未指定 |
reimport_company_id | string (uuid) | null | 否 | 未指定 |
scopes | ImportBundleScope[] | 是 | 未指定 |
範例
空租戶(各範圍都沒有有效資料表)
{
"pathParams": {},
"query": {
"include_records": "true",
"max_records": "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 契約而匯出。 | |