# 查询任务列表

列出当前工作区中你有读取权限的导入任务。先从响应中取得任务 ID，再查询详情、文件和运行记录。

```text
GET https://moi.matrixorigin.cn/newmoi/task/list
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要查询的工作区 ID，通过 `X-Workspace-ID` Header 传递。

## 查询参数

本文中，类型后的 `[]` 表示数组，例如 `integer[]` 是整数数组。

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `page` | integer | 否 | 页码。默认值为 `1`。 |
| `page_size` | integer | 否 | 每页条数。默认值为 `20`。 |
| `keyword` | string | 否 | 关键字筛选。 |
| `order_by` | string | 否 | 排序字段：`name`、`created_at`、`updated_at`、`started_at`、`ended_at`、`status`、`start_at` 或 `end_at`。默认按 `created_at` 排序。 |
| `is_desc` | boolean | 否 | 是否降序；未传入时为降序。 |
| `status` | integer（整数数组） | 否 | 按任务状态筛选；可重复传入。状态代码：`0` 未知、`1` 进行中、`2` 暂停中、`3` 已暂停、`4` 已完成、`5` 已失败。 |
| `connector_sources` | integer（整数数组） | 否 | 按连接器来源类型筛选；可重复传入。 |
| `load_interval_types` | integer（整数数组） | 否 | 按载入周期类型筛选；可重复传入。`0` 未知、`1` 每天、`2` 每小时、`3` 每分钟、`4` 一次性、`5` 每 5 分钟、`6` 每 10 分钟、`7` 每 30 分钟、`8` 每 2 小时、`9` 每 4 小时、`10` 每 6 小时、`11` 每 12 小时。 |
| `source_connector_ids` | string（字符串数组） | 否 | 按来源连接器 ID 筛选；可重复传入。 |

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/task/list?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

成功时返回 `200`。保存任务 ID，不要根据名称推断 ID。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "tasks": [
      {
        "id": "task_01",
        "name": "import_orders",
        "config_type": 1,
        "source_connector_id": "conn_01",
        "connector_name": "orders_mysql",
        "volume_id": "vol_01",
        "status": 2,
        "total_rows": 100,
        "imported_rows": 100,
        "success_file_count": 1,
        "failed_file_count": 0
      }
    ],
    "total": 1
  }
}
```

响应字段如下。

本文中，类型后的 `[]` 表示数组，例如 `string[]` 是字符串数组；字段路径中的 `[]` 表示数组中的每一项，例如 `data.tasks[].id` 表示 `data.tasks` 数组中每一项的 `id` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.tasks` | object（对象数组） | 当前调用者可读取的任务。每个元素的完整字段见[导入任务对象字段](import-task-object-fields.md)。 |
| `data.tasks[].id` | string | 任务 ID。 |
| `data.tasks[].name` | string | 任务名称。 |
| `data.tasks[].config_type` | integer | 任务配置类型：`1` 文件导入、`2` 数据库导入、`3` 结构化载入。 |
| `data.tasks[].source_connector_id` | string | 来源连接器 ID。 |
| `data.tasks[].source_connector_type` | integer | 来源连接器类型代码。 |
| `data.tasks[].connector_name` | string | 来源连接器名称。 |
| `data.tasks[].volume_id` | string | 目标 Volume ID。 |
| `data.tasks[].volume_name` | string | 目标 Volume 名称。 |
| `data.tasks[].volume_path` | object | 目标 Volume 中的路径标识。 |
| `data.tasks[].volume_path.id_list` | string（字符串数组） | 路径中各层级的 ID。 |
| `data.tasks[].volume_path.name_list` | string（字符串数组） | 路径中各层级的名称。 |
| `data.tasks[].creator` | string | 创建任务的用户标识。 |
| `data.tasks[].status` | integer | 任务当前状态代码：`0` 未知、`1` 进行中、`2` 暂停中、`3` 已暂停、`4` 已完成、`5` 已失败。 |
| `data.tasks[].source_config` | object | 类型专属来源配置。 |
| `data.tasks[].start_at` | integer | 开始时间的 Unix 时间戳。 |
| `data.tasks[].end_at` | integer | 结束时间的 Unix 时间戳。 |
| `data.tasks[].created_at` | integer | 创建时间的 Unix 时间戳。 |
| `data.tasks[].updated_at` | integer | 更新时间的 Unix 时间戳。 |
| `data.tasks[].file_types` | integer（整数数组） | 文件类型筛选代码。 |
| `data.tasks[].path_regex` | string | 文件路径筛选正则表达式；未设置时为空字符串。 |
| `data.tasks[].unzip_keep_structure` | boolean | 解压文件时是否保留目录结构。 |
| `data.tasks[].dedup` | object | 去重配置；未设置时为 `null`。 |
| `data.tasks[].dedup.by` | string（字符串数组） | 去重所用字段。 |
| `data.tasks[].dedup.strategy` | string | 去重策略。 |
| `data.tasks[].table_path` | object | 单表目标路径标识。 |
| `data.tasks[].table_paths` | object（对象数组） | 多表目标路径标识；没有多表配置时可能省略。 |
| `data.tasks[].table_path.id_list` | string（字符串数组） | 单表目标路径中各层级的 ID。 |
| `data.tasks[].table_path.name_list` | string（字符串数组） | 单表目标路径中各层级的名称。 |
| `data.tasks[].table_paths[].id_list` | string（字符串数组） | 多表目标路径中各层级的 ID。 |
| `data.tasks[].table_paths[].name_list` | string（字符串数组） | 多表目标路径中各层级的名称。 |
| `data.tasks[].source_files` | string（二维字符串数组） | 来源文件信息；每个元素依次为连接器名称和文件 URI。 |
| `data.tasks[].load_type` | integer | 载入方式代码。 |
| `data.tasks[].load_results` | object（对象数组） | 各文件或表的载入结果。 |
| `data.tasks[].load_results[].lines` | integer | 此结果中的行数。 |
| `data.tasks[].load_results[].reason` | string | 此结果的失败原因。 |
| `data.tasks[].total_rows` | integer | 任务总行数。 |
| `data.tasks[].imported_rows` | integer | 已导入行数。 |
| `data.tasks[].success_file_count` | integer | 成功文件数。 |
| `data.tasks[].failed_file_count` | integer | 失败文件数。 |
| `data.tasks[].latest_rows` | object | 最近一次运行的行统计；未采集时可能省略。 |
| `data.tasks[].cumulative_rows` | object | 累计行统计；未采集时可能省略。 |
| `data.tasks[].latest_rows.read_rows` | integer | 最近一次运行读取的行数。 |
| `data.tasks[].latest_rows.succeeded_rows` | integer | 最近一次运行成功处理的行数。 |
| `data.tasks[].latest_rows.failed_rows` | integer | 最近一次运行失败的行数。 |
| `data.tasks[].latest_rows.skipped_rows` | integer | 最近一次运行跳过的行数。 |
| `data.tasks[].latest_rows.complete` | boolean | 最近一次运行的行统计是否完整。 |
| `data.tasks[].cumulative_rows.read_rows` | integer | 累计读取的行数。 |
| `data.tasks[].cumulative_rows.succeeded_rows` | integer | 累计成功处理的行数。 |
| `data.tasks[].cumulative_rows.failed_rows` | integer | 累计失败的行数。 |
| `data.tasks[].cumulative_rows.skipped_rows` | integer | 累计跳过的行数。 |
| `data.tasks[].cumulative_rows.complete` | boolean | 累计行统计是否完整。 |
| `data.tasks[].error_code` | string | 当前错误代码；无错误时可能省略。 |
| `data.tasks[].error_summary` | string | 当前错误摘要；无错误时可能省略。 |
| `data.tasks[].target_path_state` | string | 目标路径状态。 |
| `data.tasks[].target_path_error_code` | string | 目标路径解析或校验失败时的错误代码；没有错误时可能省略。 |
| `data.tasks[].target_path_error_summary` | string | 目标路径解析或校验失败时的错误摘要；没有错误时可能省略。 |
| `data.tasks[].structured_load_config` | object | 结构化载入的完整配置；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].structured_load_summary` | object | 结构化载入摘要；仅 `config_type` 为 `3` 时可能返回，包含来源、目标、映射、计划、回填、进度、检查点和对账摘要。 |
| `data.tasks[].structured_load_summary.source_type` | string | 结构化载入的来源类型。 |
| `data.tasks[].structured_load_summary.source_object` | string | 结构化载入的来源对象。 |
| `data.tasks[].structured_load_summary.target_database_id` | string | 目标数据库 ID。 |
| `data.tasks[].structured_load_summary.target_table_id` | string | 目标表 ID。 |
| `data.tasks[].structured_load_summary.target_table_name` | string | 目标表名称。 |
| `data.tasks[].structured_load_summary.source.connector_id` | string | 来源连接器 ID；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.connector_name` | string | 来源连接器名称；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.source_type` | string | 来源对象类型；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.database` | string | 来源数据库名称；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.schema` | string | 来源 Schema 名称；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.table` | string | 来源表名称；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.collection` | string | 来源集合名称；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.source.object` | string | 来源对象名称；不适用时可能省略。 |
| `data.tasks[].structured_load_summary.target.mode` | string | 目标写入模式。 |
| `data.tasks[].structured_load_summary.target.database_id` | string | 目标数据库 ID。 |
| `data.tasks[].structured_load_summary.target.database_name` | string | 目标数据库名称。 |
| `data.tasks[].structured_load_summary.target.table_id` | string | 目标表 ID。 |
| `data.tasks[].structured_load_summary.target.table_name` | string | 目标表名称。 |
| `data.tasks[].structured_load_summary.mapping_count` | integer | 映射数量。 |
| `data.tasks[].structured_load_summary.backfill_progress_percent` | integer | 回填进度百分比。 |
| `data.tasks[].structured_load_summary.mapping` | JSON | 映射配置。 |
| `data.tasks[].structured_load_summary.schedule` | JSON | 调度配置。 |
| `data.tasks[].structured_load_summary.backfill` | JSON | 回填配置。 |
| `data.tasks[].structured_load_summary.run_mode` | string | 运行模式。 |
| `data.tasks[].structured_load_summary.sync_strategy` | string | 同步策略。 |
| `data.tasks[].structured_load_summary.backfill_phase` | string | 回填阶段。 |
| `data.tasks[].structured_load_summary.runtime_init_status` | string | 运行时初始化状态。 |
| `data.tasks[].structured_load_summary.priority` | string | 优先级。 |
| `data.tasks[].structured_load_summary.config_hash` | string | 配置哈希。 |
| `data.tasks[].structured_load_summary.backfill_enabled` | boolean | 是否启用回填。 |
| `data.tasks[].structured_load_summary.progress.total_rows` | integer | 载入进度的总行数；没有进度信息时 `progress` 可能省略。 |
| `data.tasks[].structured_load_summary.progress.imported_rows` | integer | 载入进度的已导入行数；没有进度信息时 `progress` 可能省略。 |
| `data.tasks[].structured_load_summary.progress.progress_percent` | integer | 载入进度百分比；没有进度信息时 `progress` 可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.source_object_hash` | string | 检查点的来源对象哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.structured_config_hash` | string | 检查点的结构化配置哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.source_schema_hash` | string | 检查点的来源 Schema 哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.capability_profile_hash` | string | 检查点的能力配置哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.order_policy_hash` | string | 检查点的排序策略哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.consistency_proof_hash` | string | 检查点的一致性证明哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.lock_owner_run_id` | string | 检查点锁所属运行 ID；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.lock_phase` | string | 检查点锁所处阶段；没有检查点时可能省略。 |
| `data.tasks[].structured_load_summary.checkpoint.lock_expires_at` | integer | 检查点锁的到期 Unix 时间戳；没有锁时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.id` | string | 对账记录 ID；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.run_id` | string | 对账运行 ID；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.phase` | string | 对账阶段；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.status` | string | 对账状态；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.error_code` | string | 对账错误代码；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.error_message` | string | 对账错误信息；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.created_table_id` | string | 对账时创建的表 ID；没有对账信息时可能省略。 |
| `data.tasks[].structured_load_summary.reconcile.updated_at` | integer | 对账记录的更新时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_load_summary.reconcile.resolved_at` | integer | 对账记录的解决时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime` | object | 结构化载入运行时信息；仅 `config_type` 为 `3` 时可能返回，包含初始化状态、配置哈希、运行状态、检查点、回填、映射、进度、对账和最近一次运行。 |
| `data.tasks[].structured_runtime.runtime_init_status` | string | 运行时初始化状态。 |
| `data.tasks[].structured_runtime.config_hash` | string | 运行时配置哈希。 |
| `data.tasks[].structured_runtime.run_status` | string | 运行状态。 |
| `data.tasks[].structured_runtime.checkpoint_status` | string | 检查点状态。 |
| `data.tasks[].structured_runtime.backfill` | JSON | 回填数据。 |
| `data.tasks[].structured_runtime.schema_snapshot` | JSON | Schema 快照数据。 |
| `data.tasks[].structured_runtime.mapping` | JSON | 映射数据。 |
| `data.tasks[].structured_runtime.progress.total_rows` | integer | 载入进度的总行数；没有进度信息时 `progress` 可能省略。 |
| `data.tasks[].structured_runtime.progress.imported_rows` | integer | 载入进度的已导入行数；没有进度信息时 `progress` 可能省略。 |
| `data.tasks[].structured_runtime.progress.progress_percent` | integer | 载入进度百分比；没有进度信息时 `progress` 可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.source_object_hash` | string | 检查点的来源对象哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.structured_config_hash` | string | 检查点的结构化配置哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.source_schema_hash` | string | 检查点的来源 Schema 哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.capability_profile_hash` | string | 检查点的能力配置哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.order_policy_hash` | string | 检查点的排序策略哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.consistency_proof_hash` | string | 检查点的一致性证明哈希；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.lock_owner_run_id` | string | 检查点锁所属运行 ID；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.lock_phase` | string | 检查点锁所处阶段；没有检查点时可能省略。 |
| `data.tasks[].structured_runtime.checkpoint.lock_expires_at` | integer | 检查点锁的到期 Unix 时间戳；没有锁时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.id` | string | 对账记录 ID；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.run_id` | string | 对账运行 ID；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.phase` | string | 对账阶段；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.status` | string | 对账状态；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.error_code` | string | 对账错误代码；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.error_message` | string | 对账错误信息；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.created_table_id` | string | 对账时创建的表 ID；没有对账信息时可能省略。 |
| `data.tasks[].structured_runtime.reconcile.updated_at` | integer | 对账记录的更新时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime.reconcile.resolved_at` | integer | 对账记录的解决时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime.last_run.id` | string | 最近一次运行 ID；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.run_status` | string | 最近一次运行状态；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.error_message` | string | 最近一次运行的错误信息；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.source_schema_hash` | string | 最近一次运行的来源 Schema 哈希；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.source_object_hash` | string | 最近一次运行的来源对象哈希；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.structured_config_hash` | string | 最近一次运行的结构化配置哈希；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.trigger_id` | string | 最近一次运行的触发器 ID；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.trigger_source` | string | 最近一次运行的触发来源；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.workflow_execution_id` | string | 最近一次运行的工作流执行 ID；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.mowl_task_id` | string | 最近一次运行的 MOWL 任务 ID；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.moi_case_id` | string | 最近一次运行的 MOI case ID；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.current_phase` | string | 最近一次运行的当前阶段；没有运行记录时可能省略。 |
| `data.tasks[].structured_runtime.last_run.status` | integer | 最近一次运行的状态代码。 |
| `data.tasks[].structured_runtime.last_run.row_count` | integer | 最近一次运行处理的行数。 |
| `data.tasks[].structured_runtime.last_run.file_count` | integer | 最近一次运行处理的文件数。 |
| `data.tasks[].structured_runtime.last_run.scheduled_fire_at` | integer | 最近一次运行的计划触发时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime.last_run.started_at` | integer | 最近一次运行的开始时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime.last_run.ended_at` | integer | 最近一次运行的结束时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime.last_run.created_at` | integer | 最近一次运行的创建时间，使用 Unix 时间戳。 |
| `data.tasks[].structured_runtime.last_run.updated_at` | integer | 最近一次运行的更新时间，使用 Unix 时间戳。 |
| `data.tasks[].mapping` | JSON | 结构化载入的映射配置；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].schedule` | JSON | 结构化载入的调度配置；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].backfill` | JSON | 结构化载入的回填配置；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].runtime_init_status` | string | 结构化载入的初始化状态；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].priority` | string | 结构化载入的优先级；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].config_hash` | string | 结构化载入的配置哈希；仅 `config_type` 为 `3` 时可能返回。 |
| `data.tasks[].structured_config_hash` | string | 结构化载入的结构化配置哈希；仅 `config_type` 为 `3` 时可能返回。 |
| `data.total` | integer | 匹配条件的任务总数。 |

## 错误响应

```json
{
  "code": "ErrForbidden",
  "msg": "permission denied",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 25 30 33

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 查询参数无效。
  - 修正分页或筛选参数。
* - `403`
  - `ErrForbidden`
  - 调用者没有读取任务集合的权限。
  - 检查工作区授权。
* - `503`
  - `ErrCoreAuthorizeUnavailable`
  - 服务暂时无法完成授权筛选。
  - 稍后重试；不要把空列表视为没有任务。
* - `200`
  - `ErrServer`
  - 服务未能列出任务。
  - 同时检查 HTTP 状态和 `code`。
```

## 后续操作

保存目标任务的 ID，再[查询任务详情](get-import-task.md)。