# 导入表格文档

`POST` `/api/knowledge/document/importTable`

将已上传的 Excel/CSV 表格文件按用户配置的列映射规则导入知识库，基于表头行号、数据起始行号、列到语义层级（一/二/三级标题/正文）的映射，生成结构化的语义树。导入前应先通过 /document/parseTableStructure 读取列名作为映射依据。API Key / OpenAPI 调用可导入整个应用空间（X-App-Id）内的知识库，用户控制台调用可导入该用户自己创建的知识库；越出范围返回 403。新上传文件的libraryId、fileName、fileSize、documentUsageId由后端上传记录恢复，客户端可省略；显式知识库或用量身份与记录不符时拒绝。升级前无记录的文件仍兼容原有参数。导入是异步流程。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| documentUsageId | string | 否 | 可选文档用量身份；新上传文件自动关联预分析，提供时必须一致；历史请求仍可沿用预分析返回值 |
| libraryId | integer | 否 | 可选目标知识库ID；新上传文件由后端恢复，提供时必须一致；历史无记录文件需提供 |
| ossKey | string | 是 | 文件上传后返回的OSS Key |
| fileName | string | 否 | 可选原始文件名；以服务端上传记录为准，历史无记录时兼容使用 |
| tableConfig | TableConfig | 是 | 表结构配置 |
|     headerRow | integer | 是 | 表头所在行号 |
|     dataStartRow | integer | 是 | 数据起始行号 |
|     columns | array | 是 | 列映射配置列表 |
|         columnIndex | integer | 是 | 列索引（从0开始） |
|         columnName | string | 否 | 列名 |
|         mappingType | string | 否 | 映射类型：title_1(一级标题)/title_2(二级标题)/title_3(三级标题)/content(正文) |
| fileSize | integer | 否 | 文件大小（字节），由上传接口返回 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |