# 查询工作流作业导入文件列表

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

分页查询工作流作业关联导入任务的文件级处理记录，支持按导入文件状态筛选。结构化载入任务或未关联导入任务的作业返回空数组 `data.files`。

```text
GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/{workflow_id}/executions/{execution_id}/import-files
```

## 调用前准备

1. 准备具有工作流作业读取权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。
2. 先[启动工作流作业](start-workflow-job.md#成功响应)或[查询工作流作业列表](list-workflow-jobs.md#成功响应)，取得工作流 ID 和作业 ID；也可先[查询工作流作业导入上下文](get-workflow-job-import-context.md)确认作业是否关联导入运行记录。

## 请求参数

将 `$AI_STUDIO_API_KEY`、`$WORKSPACE_ID`、`$WORKFLOW_ID` 和 `$EXECUTION_ID` 替换为实际值。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

### 读取第一页

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/import-files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20"
```

### 按状态筛选失败文件

状态代码 `3` 表示导入失败的文件。可通过英文逗号分隔值或重复 `status` 查询参数同时筛选多个状态。

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/import-files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "status=3"
```

### 读取下一页

每次将 `page` 加 `1`，直至已读取的文件总数达到 `data.total`，或当前页返回的 `data.files` 为空数组时停止翻页。

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/import-files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=2" \
  --data-urlencode "page_size=20"
```

:::::
:::::{tab-item} 参数说明

### 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workflow_id` | string | 是 | 工作流 ID。传入该路径参数时，若目标作业不属于指定工作流则返回 `404`。 |
| `execution_id` | string | 是 | 工作流作业 ID。 |

### 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `page` | integer | 否 | 页码，必须为非负整数；省略或传 `0` 时读取第 `1` 页。传入负数或非整数时返回 `400`。 |
| `page_size` | integer | 否 | 每页返回条数，取值范围为 `0`–`1000`；省略或传 `0` 时默认返回 `20` 条。超出范围或非整数时返回 `400`。 |
| `status` | string | 否 | 按导入文件状态代码筛选。支持传单个整数、英文逗号分隔的多个整数（如 `2,3`）或重复传入多个 `status` 查询参数。取值为 `1` 待处理、`2` 上传中、`3` 失败、`4` 成功。 |

仅按 `execution_id` 查询且不指定 `workflow_id` 时，可调用 `GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/executions/{execution_id}/import-files`。当存在导入失败文件且需要重新导入时，可将失败文件的 `data.files[].id` 传给[重试导入失败文件](../../data-connections/import-tasks/retry-failed-import-files.md)。

:::::
::::::
:::::::

## 成功响应

`data.total` 为当前 `status` 筛选条件下的匹配文件总数；`data.total_sum` 为该次导入运行的全部文件总数。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "import_context": {
      "task_id": "task-001",
      "task_name": "orders-import",
      "run_id": "run-001",
      "workflow_execution_id": "exec-001",
      "workflow_app_id": "wf-001",
      "moi_task_id": "mowl-task-001",
      "moi_case_id": "mowl-case-001",
      "status": 4,
      "error_message": "1 file failed",
      "row_count": 900,
      "file_count": 4,
      "total": 4,
      "total_success": 3,
      "total_failed": 1,
      "started_at": "2026-08-28T10:00:00Z",
      "ended_at": "2026-08-28T10:02:15Z",
      "created_at": "2026-08-28T09:59:58Z"
    },
    "files": [
      {
        "id": "file-001",
        "name": "orders_20260828.csv",
        "type": 1,
        "status": 3,
        "size": 20480,
        "update_time": 1756375335,
        "reason": "column count mismatch at line 42",
        "user": "alice",
        "start_time": 1756375200,
        "end_time": 1756375335,
        "path": "imports/orders/orders_20260828.csv",
        "run_id": "run-001"
      }
    ],
    "total": 1,
    "total_sum": 4,
    "total_success": 3,
    "total_failed": 1
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 请求处理成功时为 `OK`。 |
| `msg` | string | 请求处理的说明文本。 |
| `data` | object | 本次操作返回的数据。 |
| `data.import_context` | object | 关联的导入运行上下文；作业未关联导入任务时省略。 |
| `data.import_context.task_id` | string | 关联的导入任务 ID。 |
| `data.import_context.task_name` | string | 导入任务名称。 |
| `data.import_context.run_id` | string | 导入运行记录 ID。 |
| `data.import_context.workflow_execution_id` | string | 关联的工作流作业 ID。 |
| `data.import_context.workflow_app_id` | string | 关联的工作流 ID。 |
| `data.import_context.moi_task_id` | string | 服务端任务标识。 |
| `data.import_context.moi_case_id` | string | 服务端运行实例标识。 |
| `data.import_context.status` | integer | 导入运行状态代码：`1` 已创建、`2` 运行中、`3` 已完成、`4` 已失败、`5` 已取消。 |
| `data.import_context.error_message` | string | 导入运行错误信息；无错误时省略。 |
| `data.import_context.row_count` | integer | 本次导入处理或写入的行数。 |
| `data.import_context.file_count` | integer | 导入运行记录上的文件数；结构化载入任务为 `0`。 |
| `data.import_context.total` | integer | 按文件状态统计的文件总数；结构化载入任务为 `0`。 |
| `data.import_context.total_success` | integer | 导入成功的文件数；结构化载入任务为 `0`。 |
| `data.import_context.total_failed` | integer | 导入失败的文件数；结构化载入任务为 `0`。 |
| `data.import_context.started_at` | string | 开始时间，采用 RFC 3339 格式；未记录时省略。 |
| `data.import_context.ended_at` | string | 结束时间，采用 RFC 3339 格式；未记录时省略。 |
| `data.import_context.created_at` | string | 创建时间，采用 RFC 3339 格式；未记录时省略。 |
| `data.files` | array of object | 当前页的导入文件记录列表。没有匹配项、未关联导入任务或属于结构化载入任务时为空数组。 |
| `data.files[].id` | string | 导入文件记录 ID。 |
| `data.files[].name` | string | 文件名称。 |
| `data.files[].type` | integer | 文件类型代码。 |
| `data.files[].status` | integer | 导入文件状态代码：`1` 待处理、`2` 上传中、`3` 失败、`4` 成功。 |
| `data.files[].size` | integer | 文件大小，单位为字节。 |
| `data.files[].update_time` | integer | 最近更新时间的 Unix 秒级时间戳；未记录时为 `0`。 |
| `data.files[].reason` | string | 文件导入失败原因；无错误时省略。 |
| `data.files[].user` | string | 导入任务所属用户名；为空时省略。 |
| `data.files[].start_time` | integer | 开始处理时间的 Unix 秒级时间戳；未记录时为 `0`。 |
| `data.files[].end_time` | integer | 结束处理时间的 Unix 秒级时间戳；未记录时为 `0`。 |
| `data.files[].path` | string | 文件保存路径；为空时省略。 |
| `data.files[].run_id` | string | 所属导入运行记录 ID。 |
| `data.total` | integer | 当前筛选条件下的文件总数。 |
| `data.total_sum` | integer | 本次导入运行的全部文件数。 |
| `data.total_success` | integer | 本次导入运行成功的文件数。 |
| `data.total_failed` | integer | 本次导入运行失败的文件数。 |

:::::
::::::
:::::::

## 错误响应

分页参数超出允许范围、`status` 包含非整数文本、目标作业不存在或当前身份无权访问该作业时返回错误。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "ErrParamInvalid",
  "msg": "Bad Request"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码。 |
| `msg` | string | 可读错误信息。 |

:::::
::::::
:::::::

### 常见 HTTP 错误

```{list-table}
:header-rows: 1

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - 400
  - `ErrParamInvalid`、`ErrWorkspaceRequired`
  - `page` 为负数、`page_size` 不在 `0`–`1000` 范围内、`status` 非整数，或缺少工作区请求头。
  - 修正分页与状态筛选参数后再提交。
* - 401
  - `Unauthorized`
  - 认证凭据缺失或已失效。
  - 检查个人访问令牌是否有效。
* - 403
  - `ErrForbidden`
  - 当前身份无权读取该工作流作业的导入文件列表。
  - 使用有权限的身份，或联系管理员授权。
* - 404
  - `ErrNotFound`
  - 作业不存在，或作业不属于路径指定的 `workflow_id`。
  - 核对 `execution_id`、`workflow_id` 和目标工作区。
* - 500
  - `ErrServer`
  - `status` 传入未定义的状态码，或服务端读取导入文件列表失败。
  - 仅使用状态码 `1`、`2`、`3`、`4`，并稍后核对导入记录。
* - 503
  - `ErrServiceUnavailable`
  - 授权或存储依赖暂不可用。
  - 稍后重试查询。
```
