后台任务 tasks

异步操作的任务队列;可查看、取消待执行任务、重试失败任务。

点击任一接口,右侧显示对应的调用示例。

运维与系统鉴权: 仅管理员2 个接口

鉴权

请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。

X-API-Key

鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。

约定

分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。

时间一律 RFC 3339(UTC);金额单位为分。

写操作成功回 200/201/204;重复提交按资源唯一键回 409。

GET/api/v2/tasks列出后台任务

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
sortstring 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
statusTaskStatus 按状态过滤。
可选值 ["pending","running","done","failed"]
idsstring 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。
typestring 按任务类型过滤。
typesstring 只看这些显示类型(Task.subject):逗号分隔,去重后至多 200 个、每项至多 64 个字符(超了 422),命中其中任一个;node.cmd 匹配全部节点指令(node.cmd:*)。与 type 同给取交集。
qstring 搜索:#123 或纯数字匹配任务 ID 与 ID 为它的站点/节点/证书;IP 或 CIDR 匹配该 IP 对象;其它文字按节点名、站点名、站点域名、证书名模糊匹配。租户凭据不匹配节点。迁移前的旧任务搜不到。
routineboolean 例行任务(定时、只读查询):false 只看非例行,true 只看例行;不给为全部。
open_failedboolean false 时排除「待处理失败」(失败、未取消、未忽略、未自动恢复;这些由 GET /tasks/fail-groups 分组列出);不给或 true 不排除。
GET/api/v2/tasks/{id}获取后台任务

鉴权: 用户(部分参数仅管理员)

后台任务对象

字段类型说明
attemptsinteger 已尝试次数。
auto_recoveredinteger 同样筛选条件下已自动恢复的失败数。
cancelledboolean 已取消(状态为失败且 last_error 为 cancelled)。
created_atstring 创建时间
doneinteger[] 处理成功的任务 ID。
duration_snumber 耗时秒数(结束时间 − 开始时间,不足 1 秒照实给小数);只有成功或失败且有开始时间时给,否则为 null。
finished_atstring 结束时间;未结束为 null。
groupsTaskFailGroup[] 分组,按最近一次失败时刻降序。
idinteger 记录 ID
ids必填integer[] 任务 ID。
ignoredboolean 失败已被忽略。
last_errorstring 最近一次错误
max_attemptsinteger 最多尝试次数。
objectTaskObject 任务作用的对象;租户凭据看不到节点项。
progressTaskProgress 进度;只有执行中的任务给,其它为 null。
reasonTaskReason 结构化失败原因;只有失败且未取消的任务给,其它为 null。
recoveredboolean 失败已自动恢复(之后同类型同对象的任务成功了)。
retryableboolean 能否重试:白名单类型(封禁、解封、清缓存、预热)、非例行、失败(含已取消)、未自动恢复;是否已过时只在重试时检查。
routineboolean 例行任务(定时、只读查询),面板默认隐藏。
run_afterstring 最早可执行时间。
skippedTaskBatchSkip[] 跳过的任务与原因。
started_atstring 最近一次开始执行的时间;没执行过或升级前的旧任务为 null。
statusTaskStatus 任务状态:pending 待执行、running 执行中、done 完成、failed 失败。
可选值 ["pending","running","done","failed"]
subjectstring 显示类型:队列 kind;节点指令为 node.cmd:<指令名>。
tenant_idinteger 发起任务的租户;系统任务为 null。
titlestring 发起方给的简短说明。
truncatedboolean 待处理失败超过 2000 条,只按最新的 2000 条分组。
typestring 任务类型(队列 kind)。
updated_atstring 更新时间

返回与错误

成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。

成功
{
  "id": 1,
  "name": "example"
}
列表
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
失败
{
  "code": "validation_failed",
  "detail": "请求参数不合法",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name 必填"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
开始使用

体验在线演示

访问在线演示,或联系我们获取报价与安装命令