预览文件¶

读取临时文件或连接器内文件的预览内容。

POST https://api.moi.matrixorigin.cn/v5/connectors/file/preview

调用前准备¶

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。临时文件从上传文件取得；连接器内文件从查看文件列表取得连接器 ID 和文件 URI。

请求体¶

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和示例中的文件标识替换为实际值。

输入示例

预览临时文件

curl -X POST "https://api.moi.matrixorigin.cn/v5/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\": 2,
    \"columnNameRow\": 1,
    \"isColumnName\": true
  }"

预览连接器内文件

读取连接器内文件需要该连接器的使用权限。

curl -X POST "https://api.moi.matrixorigin.cn/v5/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\": 2,
    \"columnNameRow\": 1,
    \"isColumnName\": true
  }"

调整解析方式

需要预览指定的工作表或调整文件解析方式时，使用以下独立请求。每次只传入当前场景需要的字段。

预览指定工作表

对 XLS 或 XLSX 文件，使用 sheet_name 选择工作表。file_type 大于 0 时，覆盖按文件名或 URI 推断的类型；示例使用 XLSX 的类型代码 25。

curl -X POST "https://api.moi.matrixorigin.cn/v5/connectors/file/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d @- <<EOF
{
  "conn_file_id": "$CONN_FILE_ID",
  "sheet_name": "Orders",
  "file_type": 25
}
EOF

默认

使用自定义 CSV 格式

使用 csv 配置 CSV 的字段分隔符、引用符和转义方式。示例使用 CSV 的类型代码 7。

curl -X POST "https://api.moi.matrixorigin.cn/v5/connectors/file/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d @- <<EOF
{
  "conn_file_id": "$CONN_FILE_ID",
  "file_type": 7,
  "csv": {
    "separator": ";",
    "delimiter": "\"",
    "isEscape": false
  }
}
EOF

参数说明

预览临时文件

参数	类型	是否必填	说明
`conn_file_id`	string	是	临时文件 ID。
`rowStart`	integer	否	预览数据的起始行。
`columnNameRow`	integer	否	作为列名的行号。
`isColumnName`	boolean	否	是否使用列名行。

预览连接器内文件

参数	类型	是否必填	说明
`connector_id`	string 或 integer	是	已保存连接器的 ID。
`uri`	string	是	连接器内文件的 URI。
`rowStart`	integer	否	预览数据的起始行。
`columnNameRow`	integer	否	作为列名的行号。
`isColumnName`	boolean	否	是否使用列名行。

调整解析方式

参数	类型	是否必填	说明
`conn_file_id`	string	是	要预览的临时文件 ID。
`sheet_name`	string	否	要读取的工作表名称。
`file_type`	integer	否	用于解析的文件类型代码；大于 `0` 时覆盖自动识别的类型。

默认

参数	类型	是否必填	说明
`conn_file_id`	string	是	要预览的临时文件 ID。
`file_type`	integer	否	用于解析的文件类型代码；大于 `0` 时覆盖自动识别的类型。
`csv`	object	否	CSV 解析配置。
`csv.separator`	string	否	字段分隔符。
`csv.delimiter`	string	否	引用字段使用的定界符。
`csv.isEscape`	boolean	否	是否启用反斜杠转义。

成功响应¶

响应示例

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

字段说明

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data.conn_file_id`	string	本次预览使用的临时文件 ID。
`data.file_type`	integer	实际用于预览的文件类型代码。
`data.rows`	array of object	按列组织的预览数据。
`data.rows.number`	integer	列的序号。
`data.rows.columnName`	string	列名。
`data.rows.columnValues`	array of string	该列的预览值。
`data.rows.charNumber`	string	预留字段。
`data.rows.charColumnName`	string	预留字段。
`data.sheets`	array of object	电子表格工作表。
`data.sheets.name`	string	工作表名称。
`data.sheets.row_count`	integer	工作表行数。

错误响应¶

响应示例

{
  "code": "ErrIAMRequestInvalid",
  "msg": "invalid parameter",
  "data": null
}

字段说明

字段	类型	说明
`code`	string	错误代码。
`msg`	string	错误信息。
`data`	null	错误响应中为 `null`。

后续操作¶

预览连接器内文件时，只有响应返回非空 data.conn_file_id 才可下载文件或删除文件。CSV、XLS 或 XLSX 的临时文件 ID 也可用于本地上传并创建导入任务。

最后更新于 2026 年 9 月 11 日