Files
orbit/docs/api
..

Orbit HTTP / WebSocket 接口手册

更新:2026-09-18。接口实现状态随 开发计划 更新。

当前接口状态

接口 状态 手册
GET /health/live 已实现 健康检查
GET /health/ready 已实现,验证数据库、迁移记录及零外键要求 健康检查
/v1/tasks 提交、查询、分页与待执行取消 已实现,P3扩展业务键与创建时间筛选 任务接口 / 查询契约
GET /v1/tasks/{task_id}/source 已实现普通、人工重试、计划固定版本及流程历史激活/轮次来源 来源查询
POST /v1/tasks:batch P3 已实现逐项受理、独立幂等、部分结果与补交 批量任务
/v1/tasks/{task_id}:review / :retry 与 /operations P3 已实现带证据核查、关联新任务与操作审计 人工恢复
/v1/tasks/{task_id}/attempts 与尝试详情 P2 已实现 执行历史
/v1/tasks/{task_id}/attempts/{attempt_id}/evidence 与证据详情 P2 已实现 执行历史
/v1/queues 创建、查询及 :configure 控制 已实现队列并发、开始速率、积压背压与暂停/恢复 队列接口与 SDK 场景
/v1/application/resources 查询及 :configure 管理 P3 已实现跨命名空间应用配额 应用配额与 SDK 场景
任务 concurrency_key 与尝试 concurrency_token P3 已实现跨队列资源键互斥 资源键接口与 SDK 场景
任务 priority 与节点领取池 P3 已实现有界优先级加速、应用/队列轮转 优先级与公平派发
凭据校验与初始化 CLI P1 已实现 鉴权
/v1/worker/connect P2 已实现并通过阶段验收 Worker 契约、Schema
任务相对延迟 delay_ms 已实现数据库计时、原键恢复与实际执行例子 任务接口、延迟示例
任务冻结策略与 Worker retryable P3 安全重试已实现 安全重试
/v1/tasks/{task_id}:cancel 与 task.cancel 通知 P3 运行中取消已实现 取消及 SDK 场景
/v1/schedules、不可变版本、暂停/恢复及触发查询 P3 已实现 计划接口与 SDK 场景
/v1/subscriptions 及管理、交付查询与重试 已实现 HTTP、管理 SDK 和完整管理示例 订阅手册
/v1/events/connect 已实现 WSS、消息 Schema、连接 SDK 和自动消费器 消息协议 / 消费 SDK
/v1/workflow-definitions 创建、发布与固定版本读取 P4定义子项已实现,实例另用启动接口 定义接口、格式规范
/v1/workflows、步骤详情、控制、信号及操作审计 已接入HTTP与独立SDK 实例接口
历史激活/轮次/信号列表、历史激活详情及信号资源审计 已接入有界分页HTTP与独立SDK 历史查询
/v1/workflows/{id}/recovery/* 六类人工恢复 已接入有证据恢复及独立SDK 恢复接口

未实现路由返回 404。健康检查就绪不表示任务执行、定时调度或流程引擎已经可用。

业务接口统一要求

P1 业务接口已遵守下述约定,后续接口继续沿用:

  • 生产使用 HTTPS/WSS,凭据通过授权头或受控握手传递,不放入 URL。
  • 应用身份、命名空间和操作权限分别校验;知道资源 ID 不等于拥有权限。
  • 稳定幂等键与请求追踪 ID 分开;超时重报保留原键。
  • 可能超过跨语言整数精度的 ID 和执行代次使用字符串。
  • 时间为 UTC RFC 3339,时长字段带单位;查询和批量操作有上限。
  • 错误码、字段、分页游标和限制值在对应阶段实现及回归后冻结。

健康接口直接返回状态对象。已实现的业务接口使用 request_id + data / error 信封;当前实际字段以本目录手册为准,其他尚未实现的接口见 通信协议草案。

每个正式接口的文档模板

实现时必须补齐:用途与权限、HTTP 方法和路径、请求头、字段类型/必填/默认值/限制、完整请求与响应、错误码、幂等与并发规则、超时/重试/取消语义、SDK 对应方法、可运行示例、兼容版本和已覆盖的回归场景。

流程实例筛选分页与权限已接入,固定筛选沿游标分页,覆盖未执行分支的全部队列权限。