BuildTask (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}

获取构建任务列表

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

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"

按任务模式过滤

offset
integer <int64> >= 0
Default: 0

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

limit
integer <int64>
Default: 20

每页数量,默认 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 同时只能有一个 BuildTask; 已存在时返回 400 VegaBackend.BuildTask.Exist

  • streaming 模式要求 Resource 在 source_metadata.primary_keys 中声明主键。
  • batch 模式要求 build_key_fields 非空。
  • 所有字段都需要在 Resource 的 schema 中存在;否则 400。
  • 创建后 status = pending
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",
  • "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 处于 running / stopping → 409 VegaBackend.BuildTask.HasRunningExecutionerror_details 携带 { running_ids: [...] }。状态拦截不可绕过,必须先 stop 再删。
  2. 任一 id 不存在(且未启用 ignore_missing)→ 404 VegaBackend.BuildTask.NotFounderror_details 携带 { missing_ids: [...] }
  3. 全部通过 → 逐条删除,返回 204。
Authorizations:
OAuth2
path Parameters
id
required
string

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

query Parameters
ignore_missing
boolean
Default: false

放宽不存在性检查:缺失 id 视为已删除(静默跳过),其它 id 正常删。 不影响 running/stopping 拦截。

delete_active_index
boolean
Default: false

是否删除当前活跃索引;默认 false

Responses

Response samples

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

启动构建任务

合法状态转移:status ∈ {stopped, failed}pendingrunningfailed 允许重试;pending 已在队列中、completed 已结束,二者均不允许 start。 batch 任务默认按 synced_mark 续跑;incremental 任务始终 保持增量续跑,reset 对它无效。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

Authorizations:
OAuth2
path Parameters
id
required
string

BuildTask ID

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

仅对原始 execute_type=full 的任务有效;为 true 时忽略 synced_mark 并从头执行。incremental 任务始终续跑,不会改变原始 execute_type

Responses

Request samples

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

Response samples

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

停止构建任务

合法状态转移:

  • pendingstopped:任务尚在队列中,直接标记停止,worker 出队后会跳过。
  • runningstopping:正常停止,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",
  • "solution": "string",
  • "error_link": "string",
  • "error_details": null
}