API docs by Redocly

DiscoverSchedule (0.1.0)

Download OpenAPI specification:

Vega Backend 资源发现调度（DiscoverSchedule）相关 API。

DiscoverSchedule 是cron 配置实体，不直接承载执行：

  • 调度器到点触发后产出一条 trigger_type=scheduled 的 DiscoverTask（详见 discover-task.yaml）
  • 用户通过本规范增删改查 DiscoverSchedule，通过 enable/disable 控制其是否生效
  • 一次性发现走 POST /catalogs/{id}/discover（discover-task.yaml 末尾），不通过本规范

每个 DiscoverSchedule 归属一个 Physical Catalog（多对一）。Logical Catalog 不支持发现调度， catalog_id 在创建后不可修改。

端点设计遵循 [vega-backend/CLAUDE.md] 的"端点设计规则"——状态切换走动作端点 enable / disable，与 ConnectorType 风格对齐；不暴露 enabled 字段为可写。

错误码新增 VegaBackend.DiscoverSchedule.* 系列，与其它资源解耦。

创建发现调度

创建 DiscoverSchedule。name 与 catalog_id 必填，catalog 必须存在且类型为 physical；不存在返回 404 VegaBackend.Catalog.NotFound，logical catalog 返回 400。

  • body 中 enabled=true 时，worker 会在 next_run 到期后触发；false 时不会触发。
  • cron_expr 必填，标准 5 字段格式，相邻两次触发至少间隔 1 小时；非法或过于频繁时返回 400 VegaBackend.DiscoverSchedule.InvalidCronExpr。
  • strategies 可空（表示全部）；非空时元素必须是 insert / delete / update 的子集。
  • start_time / end_time 均 ≥ 0；end_time>0 时要求 start_time ≤ end_time；非法返回 400 VegaBackend.DiscoverSchedule.InvalidTimeRange。
Authorizations:
OAuth2
Request Body schema: application/json
required
expected_update_time
integer <int64> >= 1

仅 PUT 使用的必填乐观锁版本，取自最近一次查询响应的 update_time

name
required
string <= 255 characters

调度名称，必填，最大长度 255

catalog_id
required
string

关联 catalog；创建必填，PUT 时必须与当前一致

cron_expr
required
string

标准 5 字段 cron 表达式（必填），相邻两次触发至少间隔 1 小时

start_time
integer <int64> >= 0

调度生效起始时间，毫秒时间戳；0 表示无起始限制。须 ≥ 0

end_time
integer <int64> >= 0

调度结束时间，毫秒时间戳；0 表示无结束时间。 须 ≥ 0，且 end_time>0 时要求 start_time ≤ end_time

enabled
boolean

创建时可选（默认 false）；PUT 时必须与当前一致，否则 409 EnabledFieldNotAllowed

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

发现策略；省略时服务端默认 full_sync

Responses

Request samples

Content type
application/json
{
  • "expected_update_time": 1,
  • "name": "string",
  • "catalog_id": "string",
  • "cron_expr": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "enabled": true,
  • "strategy": "full_sync"
}

Response samples

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

获取调度列表

分页 + filter 获取 DiscoverSchedule 列表；支持按 name 模糊过滤。

Authorizations:
OAuth2
query Parameters
name
string

按名称模糊过滤，匹配名称中包含该值的调度

catalog_id
string

按归属 catalog 过滤

enabled
boolean

按启用状态过滤；不传表示不过滤

offset
integer <int64> >= 0
Default: 0

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

limit
integer <int64>
Default: 20

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

sort
string
Default: "update_time"
Enum: "name" "create_time" "update_time" "next_run"

排序字段

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

DiscoverSchedule ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "catalog_id": "string",
  • "catalog_name": "string",
  • "cron_expr": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "enabled": true,
  • "strategy": "full_sync",
  • "last_run": 0,
  • "next_run": 0,
  • "creator": {
    },
  • "create_time": 0,
  • "updater": {
    },
  • "update_time": 0
}

严格更新调度

严格全量替换，只允许变更"配置"字段（name / cron_expr / strategies / start_time / end_time）。下列字段约束如下：

字段 约束 失败 errcode
catalog_id 必须显式携带且等于当前值（空串 / 缺失同样视为不一致） DiscoverSchedule.CatalogMismatch（409）
enabled 必须与当前一致；状态切换走 POST .../enable disable DiscoverSchedule.EnabledFieldNotAllowed（409）

id 字段在 body 中携带时被忽略，path 为权威来源。其它系统维护字段 （last_run / next_run / 时间戳 / 操作者）携带时静默忽略；其中 expected_update_time 是更新前置条件，不属于被忽略的系统维护字段。

必须传入 expected_update_time 进行乐观并发控制。该值应取自最近一次查询响应的 update_time；若计划已被其他请求更新，返回 409 VegaBackend.DiscoverSchedule.UpdateConflict。

更新会重新计算数据库中的 next_run，worker 无需维护进程内调度状态。

Authorizations:
OAuth2
path Parameters
id
required
string

DiscoverSchedule ID

Request Body schema: application/json
required
expected_update_time
required
integer <int64> >= 1

仅 PUT 使用的必填乐观锁版本，取自最近一次查询响应的 update_time

name
required
string <= 255 characters

调度名称，必填，最大长度 255

catalog_id
required
string

关联 catalog；创建必填，PUT 时必须与当前一致

cron_expr
required
string

标准 5 字段 cron 表达式（必填），相邻两次触发至少间隔 1 小时

start_time
integer <int64> >= 0

调度生效起始时间，毫秒时间戳；0 表示无起始限制。须 ≥ 0

end_time
integer <int64> >= 0

调度结束时间，毫秒时间戳；0 表示无结束时间。 须 ≥ 0，且 end_time>0 时要求 start_time ≤ end_time

enabled
boolean

创建时可选（默认 false）；PUT 时必须与当前一致，否则 409 EnabledFieldNotAllowed

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

发现策略；省略时服务端默认 full_sync

Responses

Request samples

Content type
application/json
{
  • "expected_update_time": 1,
  • "name": "string",
  • "catalog_id": "string",
  • "cron_expr": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "enabled": true,
  • "strategy": "full_sync"
}

Response samples

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

删除调度

删除 DiscoverSchedule。数据库是调度状态的唯一事实源，删除后 worker 不再获取该计划。

不删除已有 DiscoverTask 历史——该 schedule 历史触发的 DiscoverTask 保留 schedule_id 字段作为孤儿引用，便于审计追溯。正在执行的 DiscoverTask 不受影响。

Authorizations:
OAuth2
path Parameters
id
required
string

DiscoverSchedule ID

Responses

Response samples

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

启用调度

启用 DiscoverSchedule 并重新计算 next_run。幂等：对已 enable 的 schedule 再 enable 返回 204，不报错。

Authorizations:
OAuth2
path Parameters
id
required
string

DiscoverSchedule ID

Responses

Response samples

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

停用调度

停用 DiscoverSchedule；worker 仅扫描 enabled 计划。幂等：对已 disable 的 schedule 再 disable 返回 204，不报错。

不影响已经入队 / 正在执行的 DiscoverTask；这些任务执行时已经持有所需上下文。

Authorizations:
OAuth2
path Parameters
id
required
string

DiscoverSchedule ID

Responses

Response samples

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