Figranium REST API完整参考:如何用API Key触发Task并动态传参

原创2026-10-28 11:09:161,979 阅读

Figranium REST API完整参考:如何用API Key触发Task并动态传参

Figranium 是一款开源的可视化浏览器工作流自动化工具:用积木式区块搭建复杂的浏览器操作,再通过 REST API 一键触发。本文是面向新手的 Figranium API Key 实战参考——教你如何创建 API Key、用一条 curl 命令触发已保存的 Task、通过 variables 字段动态传参,并读取执行结果。

Figranium 可视化任务编辑器与 Run Task 执行界面,支持通过 REST API 触发浏览器自动化任务

一、Figranium Task API 能做什么?

Figranium 把每个浏览器工作流保存为一个 Task(如截图中的 "Google Maps Lead Scraper"),每个 Task 都有固定的 ID 和 API 端点。借助 Task API 你可以:

  • 触发执行:POST /api/tasks/:id/api 远程运行一个已保存的 Task
  • 动态传参:在请求体中传 variables,覆盖 Task 的默认变量,复用同一个工作流处理不同输入
  • 查询结果:通过 Executions API 获取执行状态、结构化数据和截图
  • 精细授权:API Key 支持按权限(tasks:read / tasks:run / tasks:manage)和 Task 白名单双重限权

所有端点都运行在你自建的 Figranium 实例上,默认端口 11345。完整接口契约见 openapi.json。

Figranium 任务画布演示动画,展示用区块堆叠构建浏览器工作流的过程

二、第一步:创建 API Key(30秒完成)

进入 Settings → API Keys 面板(对应源码 ApiKeysPanel.tsx),点击新建,为 Key 命名并勾选所需权限:

权限 能力
tasks:read 查看 Task 列表与详情
tasks:run 触发 Task 执行、查看执行结果
tasks:manage 创建/修改/删除 Task(含 tasks:read、tasks:run 能力)

💡 只用于"跑任务 + 看结果"的集成场景,勾选 tasks:run 即可,无需给管理权限。

创建后系统会返回一次明文秘钥(secret),只会展示一次,服务端只保存加盐哈希(实现见 storage-identity.js),请务必立即保存。Key 还支持绑定 taskIds 白名单,让这把 Key 只能操作指定的几个 Task。

三、第二步:用 API Key 触发 Task

API Key 支持三种传递方式,任选其一(认证逻辑见 middleware.js):

方式 示例
请求头 x-api-key(推荐) x-api-key: <你的Key>
Authorization: Bearer Authorization: Bearer <你的Key>
请求头 key key: <你的Key>

触发 Task 的核心端点是 POST /api/tasks/:id/api(路由注册见 server.js)。最小可用请求:

curl -X POST http://localhost:11345/api/tasks/task_1730000000000/api \
  -H "x-api-key: 你的API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

请求体是可选项,支持这些字段:

字段 说明
variables 运行时变量对象,覆盖 Task 内置默认值(核心字段)
url 临时覆盖 Task 的目标 URL
runId 自定义本次执行 ID,便于日志追踪
webhookUrl 执行完成后自动 POST 结果到你的回调地址
output 可选的输出推送配置(如写入 Baserow 表格)

四、动态传参:让一个 Task 服务无限输入

这是 Figranium Task API 最实用的能力。在编辑器 Variables 标签页中为 Task 定义变量(如 query、location),并在动作里用 {$query} 模板语法引用。之后每次调用时只需在请求体覆盖变量值:

curl -X POST http://localhost:11345/api/tasks/task_1730000000000/api \
  -H "x-api-key: 你的API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"query": "coffee", "location": "Tokyo"}}'

变量合并规则(源码见 server.js):运行时传入的变量会覆盖 Task 保存的默认值,未传入的变量仍使用默认值。也就是说:

  • 编辑器里给变量设好默认值 → 不传参也能直接跑
  • 调用时传 variables → 同一 Task 处理不同城市、不同关键词、不同表单数据
  • Scrape 模式下,url、selector 等字段同样支持 {$var} 模板替换

⚠️ 注意:出于安全考虑,API Key 触发时不允许通过请求体覆盖 extractionScript(会返回 EXTRACTION_SCRIPT_OVERRIDE_FORBIDDEN),防止窄权限 Key 变成服务器端代码执行通道。

五、读取执行结果

每次触发都会生成一条执行记录,用 results:read(由 tasks:run 隐含授予)权限查询(实现见 executions.js):

# 1. 列出最近的执行摘要
curl http://localhost:11345/api/executions/list -H "x-api-key: 你的API_KEY"

# 2. 查看某次执行详情(含 outcome、status、耗时)
curl http://localhost:11345/api/executions/<executionId> -H "x-api-key: 你的API_KEY"

# 3. 拉取完整结果(结构化 data、日志、截图)
curl http://localhost:11345/api/executions/<executionId>/result -H "x-api-key: 你的API_KEY"

执行结果遵循 ExecutionResult 结构,关键字段:

字段 含义
outcome 最终结果(success / error 等)
data 提取动作产出的结构化数据
final_url 执行结束时的页面 URL
screenshot_url 执行截图地址
logs 每步执行日志
hasFullResult 是否有完整结果可供 /result 拉取

六、常用端点速查表

端点 方法 权限 用途
/api/tasks/list GET tasks:read Task 摘要列表(含 ID,触发必备)
/api/tasks GET tasks:read 完整 Task 定义
/api/tasks/:id/api POST tasks:run 触发 Task + 动态传参
/api/executions/list GET tasks:run 执行历史摘要
/api/executions/:id GET tasks:run 单次执行详情
/api/executions/:id/result GET tasks:run 完整结果数据
/api/schedules/:taskId POST/DELETE 会话认证 定时计划(可视化或 cron)

📌 不知道 Task ID?先调 GET /api/tasks/list,返回的 tasks 数组里每项都有 id 和 name。

七、错误码与排错指南

HTTP 状态 错误码 原因与对策
401 INVALID_API_KEY Key 缺失或无效,检查 x-api-key 头拼写
403 API_KEY_FORBIDDEN Key 权限不足,去 Settings 勾选对应权限
403 TASK_NOT_ALLOWED 该 Task 不在 Key 的 taskIds 白名单中
404 TASK_NOT_FOUND Task ID 写错,先用 /api/tasks/list 核对
400 EXTRACTION_SCRIPT_OVERRIDE_FORBIDDEN 移除了请求体中的 extractionScript 字段
429 TOO_MANY_REQUESTS 触发限流:执行类端点默认 100 次/分钟(见 constants.js)

其他要点:

  • 执行超时:默认单任务最长运行 15 分钟(EXECUTION_TIMEOUT_MS),超时返回 EXECUTION_TIMEOUT
  • 并发与排队:实例有并发执行上限和队列(默认排队 50 个),队列满时新请求返回 503,稍后重试即可
  • 未知 API 路径统一返回 JSON 的 API_NOT_FOUND,方便程序化处理

八、安全与最佳实践清单

  1. 最小权限原则:集成 Key 只给 tasks:run;需要白名单时绑定 taskIds,Key 泄露影响面更小
  2. 定期轮换:在 Settings → API Keys 中撤销旧 Key、创建新 Key,旧 Key 立即失效
  3. 配合 webhook:在请求体传 webhookUrl,执行完成后结果会自动推送到你的服务,省去轮询
  4. 内网加固:实例暴露公网时配置 ALLOWED_IPS 环境变量限制访问来源
  5. 备份 data/ 目录:Task、API Key 元数据和执行历史都持久化在这里

九、延伸阅读

掌握"创建 Key → 触发 Task → variables 传参 → 查询结果"这条链路后,你就可以把 Figranium 嵌入 CI/CD、定时采集脚本或业务系统,用一行 curl 驱动整个浏览器自动化流水线。

登录后查看全文
figranium