# 预览文件

读取连接器文件或临时文件的预览内容。可先上传本地文件，也可先查询连接器中的文件列表。

```text
POST https://moi.matrixorigin.cn/newmoi/connectors/file/preview
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID，以及临时文件 ID，或连接器 ID 与文件 URI。读取连接器文件需要该连接器的使用权限。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要读取文件的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONN_FILE_ID`：上传文件后返回的临时文件 ID，通过 `conn_file_id` 传递。
- `$CONNECTOR_ID` 和 `$FILE_URI`：查询连接器文件列表后取得的连接器 ID 与文件 `uri`，通过 `connector_id` 和 `uri` 传递。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `conn_file_id` | string | 条件必填 | 临时文件 ID。非空时优先使用该字段，`connector_id` 和 `uri` 不参与本次预览。 |
| `connector_id` | string 或 integer | 条件必填 | 连接器 ID。仅在 `conn_file_id` 为空时使用；同时传 `uri`。 |
| `uri` | string | 条件必填 | 连接器文件 URI。仅在 `conn_file_id` 为空时使用；同时传 `connector_id`。 |
| `sheet_name` | string | 否 | XLS 或 XLSX 文件的工作表名称。 |
| `rowStart` | integer | 否 | 预览数据的起始行；为 `0` 时从第一行开始。 |
| `columnNameRow` | integer | 否 | 作为列名的行号；仅在 `isColumnName=true` 时使用。 |
| `isColumnName` | boolean | 否 | 是否将 `columnNameRow` 指定的行作为列名。 |
| `file_type` | integer | 否 | 文件类型代码。大于 `0` 时覆盖根据文件名或 URI 推断的类型。代码含义与[查询文件列表](list-files.md)中的 `type` 相同。 |
| `csv` | object | 否 | CSV 解析配置。省略时使用逗号分隔和双引号包裹。 |
| `csv.separator` | string | 否 | 字段分隔符，使用字符串的第一个字节。 |
| `csv.delimiter` | string | 否 | 字段包裹符，使用字符串的第一个字节；省略时不使用包裹符。 |
| `csv.isEscape` | boolean | 否 | 是否将反斜杠作为包裹符的转义字符。 |

请求必须提供有效的 `conn_file_id`，或在 `conn_file_id` 为空时同时提供 `connector_id` 和 `uri`。

## 请求示例

预览刚上传的临时文件：

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/file/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"conn_file_id\": \"$CONN_FILE_ID\",
    \"rowStart\": 1,
    \"isColumnName\": true
  }"
```

预览已保存连接器中的文件：

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/file/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"uri\": \"$FILE_URI\",
    \"rowStart\": 1,
    \"isColumnName\": true
  }"
```

## 成功响应

成功时返回 `200`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "conn_file_id": "conn_file_01",
    "file_type": 1,
    "rows": [
      {
        "number": 1,
        "columnName": "id",
        "columnValues": ["1", "2"],
        "charNumber": "1",
        "charColumnName": "A"
      }
    ],
    "sheets": [
      {
        "name": "Sheet1",
        "row_count": 2
      }
    ]
  }
}
```

响应字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`items[].name` 表示 `items` 数组中每一项的 `name` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.conn_file_id` | string | 被预览的临时文件 ID。使用连接器文件预览时，内容保存为临时文件后返回该 ID；可用于下载或删除。 |
| `data.file_type` | integer | 文件类型代码。 |
| `data.rows` | object（对象数组） | 预览行。 |
| `data.rows[].number` | integer | 行号。 |
| `data.rows[].columnName` | string | 列名。 |
| `data.rows[].columnValues` | string（字符串数组） | 该列的预览值。 |
| `data.rows[].charNumber` | string | 字符位置标识。 |
| `data.rows[].charColumnName` | string | 字符位置对应的列名。 |
| `data.sheets` | object（对象数组） | 电子表格工作表；其他文件类型可能省略。 |
| `data.sheets[].name` | string | 工作表名称。 |
| `data.sheets[].row_count` | integer | 工作表行数。 |

## 错误响应

```json
{
  "code": "ErrNotFound",
  "msg": "file not found",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `—`
  - JSON 请求体无法解析。响应使用 `error` 字段，不使用标准 `code` 字段。
  - 检查 JSON 类型和格式后重试。
* - `404`
  - `ErrNotFound`
  - 临时文件或连接器文件不存在。
  - 重新查询文件并确认文件 ID 或 URI。
* - `500`
  - `ErrServer`
  - 未提供文件定位字段，或服务未能读取、保存或解析文件。
  - 传入有效的文件定位字段；检查文件格式后重试。
```

## 后续操作

确认预览行与工作表符合预期后，如响应返回临时文件 ID，可使用该 ID [创建任务](../import-tasks/create-import-task.md)。需要取得文件内容时，使用该 ID [下载文件](download-file.md)。