API docs by Redocly

DiscoverTask (0.1.0)

Download OpenAPI specification:

Vega Backend 资源发现任务（DiscoverTask）相关 API。

DiscoverTask 是执行审计记录，由两条路径产生：

  • 手动触发：POST /catalogs/{id}/discover（动作端点，本规范末尾覆盖）
  • 定时触发：worker 内部由 DiscoverSchedule（见 discover-schedule.yaml）按 cron 触发

状态机（pending → running → completed/failed/cancelled）由 worker 单向推进； 用户不能 cancel / retry / restart。对外仅暴露 list / get / delete 三类只读 + 清理操作。

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

获取发现任务列表

分页获取发现任务；支持按 catalog_id / schedule_id / status / strategy / trigger_type 过滤。

Authorizations:
OAuth2
query Parameters
catalog_id
string

按归属 catalog 过滤

schedule_id
string

按归属 DiscoverSchedule 过滤；trigger_type=manual 的 task 该字段恒为空字符串。

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

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

strategy
string
Enum: "full_sync" "create_only" "cleanup_only"

按探查策略过滤

trigger_type
string
Enum: "manual" "scheduled"

按触发方式过滤

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"

排序字段；默认按创建时间倒序。时间值为 0 时按数据库普通数值排序：升序在前、降序在后。

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

排序方向

Responses

Response samples

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

获取发现任务详情

Authorizations:
OAuth2
path Parameters
id
required
string

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

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "catalog_id": "string",
  • "catalog_name": "string",
  • "schedule_id": "string",
  • "strategy": "full_sync",
  • "trigger_type": "manual",
  • "status": "pending",
  • "progress": 0,
  • "message": "string",
  • "start_time": 0,
  • "finish_time": 0,
  • "last_progress_time": 0,
  • "result": {
    },
  • "creator": {
    },
  • "create_time": 0
}

删除发现任务（整体事务）

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

预校验顺序：

  1. 任一 id 处于 pending / running → 409 VegaBackend.DiscoverTask.HasRunningExecution， error_details 携带 { running_ids: [...] }。状态拦截不可绕过——避免删除 掉 worker 正在写入的 task 留下孤儿数据。需等待任务进入终态（completed/failed/cancelled）。
  2. 任一 id 不存在（且未启用 ignore_missing）→ 404 VegaBackend.DiscoverTask.NotFound， error_details 携带 { missing_ids: [...] }。
  3. 全部通过 → 逐条删除，返回 204。
Authorizations:
OAuth2
path Parameters
id
required
string

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

query Parameters
ignore_missing
boolean
Default: false

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

Responses

Response samples

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

手动触发 catalog 资源发现

对指定 catalog 触发一次资源发现。异步语义：服务端创建一条 trigger_type=manual 的 DiscoverTask 并立即返回 task id；实际发现执行由 worker 异步推进。客户端可用 返回的 task id 通过 GET /discover-tasks/{id} 轮询执行进度。

可选请求体 {"strategy":"full_sync|create_only|cleanup_only"}；省略时默认 full_sync。本端点保留 RPC 风格嵌套形态——是对 catalog 的动作而非创建顶层 task。

仅支持 type=physical 的 catalog；type=logical 会返回 400。

Authorizations:
OAuth2
path Parameters
id
required
string

Catalog ID

Request Body schema: application/json
optional
strategy
string
Enum: "full_sync" "create_only" "cleanup_only"

Responses

Request samples

Content type
application/json
{
  • "strategy": "full_sync"
}

Response samples

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