预览文件

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

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 推断的类型。代码含义与查询文件列表中的 type 相同。
csv	object	否	CSV 解析配置。省略时使用逗号分隔和双引号包裹。
csv.separator	string	否	字段分隔符，使用字符串的第一个字节。
csv.delimiter	string	否	字段包裹符，使用字符串的第一个字节；省略时不使用包裹符。
csv.isEscape	boolean	否	是否将反斜杠作为包裹符的转义字符。

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

请求示例

预览刚上传的临时文件：

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
  }"

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

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。

{
  "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	工作表行数。

错误响应

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

常见 HTTP 错误

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

后续操作

确认预览行与工作表符合预期后，如响应返回临时文件 ID，可使用该 ID 创建任务。需要取得文件内容时，使用该 ID 下载文件。

最后更新于 2026 年 8 月 22 日