Skip to Content
API 參考匯入資料

匯入資料

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

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；省略時使用部署環境預設值。

回應結構

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-4444-8444-444444444444"
}

錯誤

狀態發生條件錯誤本文
403此處的 403 body 來自 ChatRoomAccessRequired（角色門檻是部門管理員），不是 department extraction。Company extraction 保留自己的管理閘門；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"
}
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,
          "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
    }
  ]
}

錯誤

狀態發生條件錯誤本文
404僅 department scope：請求的部門不存在於呼叫者所屬公司。
{
  "detail": "Department not found"
}
404工作階段已過期、不存在，或屬於其他範圍。
{
  "detail": "Import session not found or expired"
}
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。

請求結構

ImportCreatePayload
欄位型別必填說明
descriptionstring | null否未指定
schema_definitionTableSchema是Final (user-edited) schema to create
signaturestring是Candidate signature from the preview
skip_invalidboolean否Skip rows that fail validation instead of failing the job
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": "44444444-4444-4444-8444-444444444444",
  "message": "Table created; rows inserting"
}

錯誤

狀態發生條件錯誤本文
400找不到簽章、編輯後的結構不相容，或對應後沒有任何有效資料列。
{
  "detail": "Candidate signature not found in this session"
}
409工作階段仍存在，但保存的來源資料列已過期。
{
  "detail": "Import data expired; re-extract the file"
}
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。

請求結構

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.
signaturestring是Candidate signature from the preview
skip_invalidboolean否Skip invalid rows instead of failing the job

回應結構

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": "44444444-4444-4444-8444-444444444444"
}

錯誤

狀態發生條件錯誤本文
400目的欄位不存在、被隱藏、屬於計算欄位，或對應後沒有任何有效資料列。
{
  "detail": "Unknown target column 'Missing column'"
}
403呼叫者沒有在目的資料表新增資料列的權限。
{
  "detail": "You do not have insert permission on this table."
}
404指定範圍內找不到資料表或匯入工作階段。
{
  "detail": "Table not found in this chatroom"
}
Last updated on
JSONL IaC附件