版本 2.4.8 · 最新
后台任务 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列出后台任务
鉴权: 用户(部分参数仅管理员)
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
sort | string | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
status | TaskStatus | 按状态过滤。 |
ids | string | 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。 |
type | string | 按任务类型过滤。 |
types | string | 只看这些显示类型(Task.subject):逗号分隔,去重后至多 200 个、每项至多 64 个字符(超了 422),命中其中任一个;node.cmd 匹配全部节点指令(node.cmd:*)。与 type 同给取交集。 |
q | string | 搜索:#123 或纯数字匹配任务 ID 与 ID 为它的站点/节点/证书;IP 或 CIDR 匹配该 IP 对象;其它文字按节点名、站点名、站点域名、证书名模糊匹配。租户凭据不匹配节点。迁移前的旧任务搜不到。 |
routine | boolean | 例行任务(定时、只读查询):false 只看非例行,true 只看例行;不给为全部。 |
open_failed | boolean | false 时排除「待处理失败」(失败、未取消、未忽略、未自动恢复;这些由 GET /tasks/fail-groups 分组列出);不给或 true 不排除。 |
GET
/api/v2/tasks/{id}获取后台任务
鉴权: 用户(部分参数仅管理员)
后台任务对象
| 字段 | 类型 | 说明 |
|---|---|---|
attempts | integer | 已尝试次数。 |
auto_recovered | integer | 同样筛选条件下已自动恢复的失败数。 |
cancelled | boolean | 已取消(状态为失败且 last_error 为 cancelled)。 |
created_at | string | 创建时间 |
done | integer[] | 处理成功的任务 ID。 |
duration_s | number | 耗时秒数(结束时间 − 开始时间,不足 1 秒照实给小数);只有成功或失败且有开始时间时给,否则为 null。 |
finished_at | string | 结束时间;未结束为 null。 |
groups | TaskFailGroup[] | 分组,按最近一次失败时刻降序。 |
id | integer | 记录 ID |
ids必填 | integer[] | 任务 ID。 |
ignored | boolean | 失败已被忽略。 |
last_error | string | 最近一次错误 |
max_attempts | integer | 最多尝试次数。 |
object | TaskObject | 任务作用的对象;租户凭据看不到节点项。 |
progress | TaskProgress | 进度;只有执行中的任务给,其它为 null。 |
reason | TaskReason | 结构化失败原因;只有失败且未取消的任务给,其它为 null。 |
recovered | boolean | 失败已自动恢复(之后同类型同对象的任务成功了)。 |
retryable | boolean | 能否重试:白名单类型(封禁、解封、清缓存、预热)、非例行、失败(含已取消)、未自动恢复;是否已过时只在重试时检查。 |
routine | boolean | 例行任务(定时、只读查询),面板默认隐藏。 |
run_after | string | 最早可执行时间。 |
skipped | TaskBatchSkip[] | 跳过的任务与原因。 |
started_at | string | 最近一次开始执行的时间;没执行过或升级前的旧任务为 null。 |
status | TaskStatus | 任务状态:pending 待执行、running 执行中、done 完成、failed 失败。 |
subject | string | 显示类型:队列 kind;节点指令为 node.cmd:<指令名>。 |
tenant_id | integer | 发起任务的租户;系统任务为 null。 |
title | string | 发起方给的简短说明。 |
truncated | boolean | 待处理失败超过 2000 条,只按最新的 2000 条分组。 |
type | string | 任务类型(队列 kind)。 |
updated_at | string | 更新时间 |
返回与错误
成功直接回资源 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"
}