指南
API
指南
API
简体中文

内置 API

在面板通过任务执行器运行的 JavaScript/TypeScript 和 Python 脚本中，QLAPI 是内置 API 入口。它使用本机预加载环境，与需要应用 token 的 HTTP OpenAPI、远程 CLI 不同；直接用普通 Node/Python 执行脚本时，不保证注入该变量。

本页依据 api.proto 和预加载客户端整理。JavaScript 方法返回 Promise；Python 方法同步返回字典。HTTP 接口的字段不一定全部出现在内置 API 中，例如任务的 work_dir 和 allow_multiple_instances 不在当前 CronItem 协议中。

方法

表中的参数均封装为一个对象传入，数组字段不可替换成单个 ID。

方法 用途 参数对象 响应类型
getEnvs 获取环境变量 { searchValue: string } EnvsResponse
createEnv 创建环境变量 { envs: EnvItem[] } EnvsResponse
updateEnv 更新环境变量 { env: EnvItem } EnvResponse
deleteEnvs 删除环境变量 { ids: int32[] } Response
moveEnv 移动环境变量 { id: int32, fromIndex: int32, toIndex: int32 } EnvResponse
disableEnvs 禁用环境变量 { ids: int32[] } Response
enableEnvs 启用环境变量 { ids: int32[] } Response
updateEnvNames 修改环境变量名称 { ids: int32[], name: string } Response
getEnvById 获取单个环境变量 { id: int32 } EnvResponse
systemNotify 发送系统通知 { title: string, content: string, notificationInfo?: NotificationInfo } Response
getCronDetail 按日志路径查询任务 { log_path: string } CronDetailResponse
createCron 创建任务 { command: string, schedule: string, name?: string, labels: string[], sub_id?: int32, extra_schedules: ExtraScheduleItem[], task_before?: string, task_after?: string } CronResponse
updateCron 更新任务 { id: int32, command?: string, schedule?: string, name?: string, labels: string[], sub_id?: int32, extra_schedules: ExtraScheduleItem[], task_before?: string, task_after?: string } CronResponse
deleteCrons 删除任务 { ids: int32[] } Response
getCrons 获取任务列表 { searchValue?: string } CronsResponse
getCronById 获取单个任务 { id: int32 } CronResponse
enableCrons 启用任务 { ids: int32[] } Response
disableCrons 禁用任务 { ids: int32[] } Response
runCrons 运行任务 { ids: int32[] } Response

? 表示协议中的可选字段；具体创建和更新仍由服务端校验。createCron 的 command/schedule 必填。更新任务时建议传回完整的命令和定时规则。getCronDetail 使用 log_path，不是任务 ID。

数据结构

EnvItem

{
  id?: number;
  name?: string;
  value?: string;
  remarks?: string;
  status?: number;
  position?: string;
}

CronItem

{
  id?: number;
  command?: string;
  schedule?: string;
  name?: string;
  labels: string[];
  sub_id?: number;
  extra_schedules: ExtraScheduleItem[];
  task_before?: string;
  task_after?: string;
  status?: number;
  log_path?: string;
  pid?: number;
  last_running_time?: string;
  last_execution_time?: string;
}

ExtraScheduleItem

{
  schedule: string;
}

Response

{
  code: number;
  message?: string;
}

EnvResponse

{
  code: number;
  data: EnvItem;
  message?: string;
}

EnvsResponse

{
  code: number;
  data: EnvItem[];
  message?: string;
}

CronResponse

{
  code: number;
  data: CronItem;
  message?: string;
}

CronsResponse

{
  code: number;
  data: CronItem[];
  message?: string;
}

CronDetailResponse

{
  code: number;
  data: CronItem;
  message?: string;
}

JavaScript 客户端将 int64 解码为字符串，例如 position 和任务时间字段。成功响应的 code 为 200；检查业务代码并捕获调用异常。

通知

systemNotify 需要 title、content；可选的 notificationInfo 覆盖系统通知配置。不传时使用面板配置。

notificationInfo.type 的枚举值包括：

gotify, goCqHttpBot, serverChan, pushDeer, bark, chat, telegramBot, dingtalkBot, weWorkBot, weWorkApp, aibotk, iGot, pushPlus, wePlusBot, email, pushMe, feishu, webhook, chronocat, ntfy, wxPusherBot, wxPusherSpt, wpush.

常见配置字段：Gotify 使用 gotifyUrl/gotifyToken/gotifyPriority；Telegram 使用 telegramBotToken/telegramBotUserId；飞书使用 larkKey/larkSecret；WxPusher SPT 使用 wxPusherSptList；WPush 使用 wpushApiKey/wpushChannel/wpushTopicCode。其余字段见通知协议。

调用示例

JavaScript

async function main() {
  const envs = await QLAPI.getEnvs({ searchValue: 'EXAMPLE' });
  console.log(envs.code);
  const tasks = await QLAPI.getCrons({ searchValue: 'demo' });
  console.log(tasks.code);
  await QLAPI.systemNotify({ title: 'Demo', content: 'Task finished' });
}

main().catch(console.error);

Python

result = QLAPI.getCrons({"searchValue": "demo"})
print(result["code"])
QLAPI.systemNotify({"title": "Demo", "content": "Task finished"})