API docs by Redocly

VEGA 引擎 · 构建任务 API (0.1.0)

Download OpenAPI specification:

Vega Backend 构建任务（BuildTask）相关 API。

BuildTask 是顶级独立资源，每条 task 关联 1 个 Resource，对其执行 streaming / batch 两种模式之一的构建。状态机：

pending → running → stopping → stopped ↘ completed ↘ failed ↘ cancelled

外部仅可触发 start / stop 两个动作；其它状态由 worker 内部转移，外部只读。 start / stop 返回 HTTP 202 且 body 为空，仅表示"指令被接受"，不表示 status 已切换；持久化 status 由 worker 实际执行时写入，客户端如需感知应轮询 GET。

端点设计遵循 [vega-backend/CLAUDE.md] 的"端点设计规则"：批量删除走 path （DELETE /build-tasks/{ids}，逗号分隔），不提供 /resources/{id}/build-tasks 嵌套列表视图——按父资源过滤一律走 GET /build-tasks?resource_id={id}。

每个新任务均有服务端分配的只读 index_name。Full BuildTask 使用新的 vega-build-<uuidv7> 物理索引；Incremental BuildTask 快照创建时 Resource 的当前 index_name，不会新建索引。索引名不承载 Resource 或 Task ID，调用方不得根据其解析业务 ID。

获取构建任务列表

分页获取构建任务；支持按 resource_id / catalog_id / status / mode / execute_type 过滤。

Authorizations:
OAuth2
query Parameters
resource_id
string

按归属 resource 过滤

catalog_id
string

按归属 catalog 过滤

status
Array of strings
Items Enum: "pending" "running" "stopping" "stopped" "completed" "failed" "cancelled"

按状态过滤；多个状态重复传递该参数，状态之间为 OR 关系。

mode
string
Enum: "streaming" "batch"

按任务模式过滤

execute_type
string
Enum: "full" "incremental"

按批处理执行方式过滤；流式任务不匹配该筛选条件

offset
integer <int64> >= 0
Default: 0

分页偏移量，>=0，默认 0

limit
integer <int64> [ -1 .. 1000 ]
Default: 20

每页数量，1-1000，-1 表示不分页，默认 20

sort
string
Default: "create_time"
Enum: "create_time" "start_time" "finish_time" "last_progress_time"

排序字段，默认按创建时间排序

direction
string
Default: "desc"
Enum: "asc" "desc"

排序方向，默认 desc

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 0
}

创建构建任务

为指定 Resource 创建构建任务。同一 Resource 同时只能有一个 active BuildTask （pending / running / stopping）；已存在 active Task 时返回 400 VegaBackend.BuildTask.Exist。终态 Task 不阻止创建新任务。

  • 当前版本暂不支持 streaming 模式。
  • batch 模式要求 primary_key_fields 和 incremental_fields 均非空。
  • 所有字段都需要在 Resource 的 schema 中存在；否则 400。
  • index_name 由服务端分配并在详情、列表响应中返回；请求体不接受该字段。
  • 创建后 status = pending。

需要所属 Catalog 的 task_manage，并通过目标 Resource 的查看权限检查。 新授权写入时 task_manage 的完整依赖为 resource_manage、view_detail； 既有授权不自动补齐，运行时不额外检查 requires。Resource 的显式查看拒绝仍生效。 读取 Resource/Catalog 的已分类错误保留原状态和错误码（如 403 Public.Forbidden、404）； 未分类读取故障返回 500。失败时不创建任务或触发调度。

Authorizations:
OAuth2
Request Body schema: application/json
required
resource_id
required
string

关联 Resource ID（必填）

mode
required
string
Enum: "streaming" "batch"

任务模式

execute_type
string
Enum: "incremental" "full"

batch 执行类型；省略时服务端默认 full

Responses

Request samples

Content type
application/json
{
  • "resource_id": "string",
  • "mode": "streaming",
  • "execute_type": "incremental"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

获取构建任务详情

Authorizations:
OAuth2
path Parameters
id
required
string

BuildTask ID；DELETE 时可传逗号分隔的 ID 列表

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "resource_id": "string",
  • "catalog_id": "string",
  • "resource_name": "string",
  • "catalog_name": "string",
  • "status": "pending",
  • "mode": "streaming",
  • "execute_type": "incremental",
  • "index_name": "string",
  • "total_count": 0,
  • "synced_count": 0,
  • "synced_mark": "string",
  • "error_msg": "string",
  • "creator": {
    },
  • "create_time": 0,
  • "start_time": 0,
  • "finish_time": 0,
  • "last_progress_time": 0,
  • "failure_detail": "string",
  • "index_config": {
    }
}

删除构建任务（整体事务）

整体事务语义：所有 id 通过预校验后才进入删除阶段，任一预校验失败整批不删。

预校验顺序：

  1. 任一 id 处于 pending / running / stopping → 409 VegaBackend.BuildTask.HasRunningExecution， error_details 携带 { active_ids: [...] }。状态拦截不可绕过；pending/running 必须先 stop，stopping 必须等待停止完成后再删。
  2. 任一 id 不存在（且未启用 ignore_missing）→ 404 VegaBackend.BuildTask.NotFound， error_details 携带 { missing_ids: [...] }。
  3. 全部通过 → 只删除结束态 Task 数据库记录，返回 204。删除 Task 不修改 Resource 本地索引状态，也不删除 OpenSearch 索引。
Authorizations:
OAuth2
path Parameters
id
required
string

BuildTask ID；DELETE 时可传逗号分隔的 ID 列表

query Parameters
ignore_missing
boolean
Default: false

放宽不存在性检查：缺失 id 视为已删除（静默跳过），其它 id 正常删。 不影响 pending/running/stopping 拦截。

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

启动构建任务

合法状态转移：status ∈ {stopped, failed} → pending → running。 failed 允许重试；pending 已在队列中、completed 已结束，二者均不允许 start。 batch 任务默认按 synced_mark 续跑；incremental 任务不支持 reset=true，传入时返回 409 VegaBackend.BuildTask.IncrementalResetUnsupported。full 任务仅在 reset=true 时清除进度并从头重建， 不修改原始 execute_type； worker 实际开始执行时会清空 error_msg。

响应 status 滞后：HTTP 202 表示"启动指令已被接受并入队"，不表示 status 已切换为 running。worker 实际执行时才会写为 running， 客户端如需确认应轮询 GET。响应 body 为空。

非幂等：对非 stopped / failed 状态的 task 调用 start 返回 409 VegaBackend.BuildTask.InvalidStateTransition。

启动前重新读取 Resource；明确的权限拒绝保留 403 Public.Forbidden， 不存在保留 404，未分类读取故障返回 500。失败时不更新任务状态或触发调度。

Authorizations:
OAuth2
path Parameters
id
required
string

BuildTask ID

Request Body schema: application/json
optional
reset
boolean
Default: false

仅对原始 execute_type=full 的任务有效；为 true 时清空进度并从头执行。incremental 任务传 true 返回 409 冲突

Responses

Request samples

Content type
application/json
{
  • "reset": false
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

停止构建任务

合法状态转移：

  • pending → stopped：任务尚在队列中，直接标记停止，worker 出队后会跳过。
  • running → stopping：正常停止，worker 在批间检查点退出后写 stopped。

响应 status 滞后：HTTP 202 表示"停止指令已被记录"。running 任务的 stopping → stopped 由 worker 异步推进，客户端可轮询 GET 拿最新 status。响应 body 为空。

非幂等：对非 pending / running 状态的 task 调 stop 返回 409； stopping 中再次 stop 也返回 409 VegaBackend.BuildTask.InvalidStateTransition。

Authorizations:
OAuth2
path Parameters
id
required
string

BuildTask ID

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}