Figranium REST API完整参考:如何用API Key触发Task并动态传参
Figranium REST API完整参考:如何用API Key触发Task并动态传参
Figranium 是一款开源的可视化浏览器工作流自动化工具:用积木式区块搭建复杂的浏览器操作,再通过 REST API 一键触发。本文是面向新手的 Figranium API Key 实战参考——教你如何创建 API Key、用一条 curl 命令触发已保存的 Task、通过 variables 字段动态传参,并读取执行结果。
一、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。
二、第一步:创建 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,方便程序化处理
八、安全与最佳实践清单
- 最小权限原则:集成 Key 只给
tasks:run;需要白名单时绑定taskIds,Key 泄露影响面更小 - 定期轮换:在 Settings → API Keys 中撤销旧 Key、创建新 Key,旧 Key 立即失效
- 配合 webhook:在请求体传
webhookUrl,执行完成后结果会自动推送到你的服务,省去轮询 - 内网加固:实例暴露公网时配置
ALLOWED_IPS环境变量限制访问来源 - 备份
data/目录:Task、API Key 元数据和执行历史都持久化在这里
九、延伸阅读
- 完整接口契约:openapi.json
- Task 执行入口与动态变量合并逻辑:server.js
- Task 管理路由(含版本快照、回滚):src/server/routes/tasks.js
- API Key 认证中间件:src/server/middleware.js
- Task 区块与动作规范:AGENT_SPEC.md
- 部署与配置总览:README.md
掌握"创建 Key → 触发 Task → variables 传参 → 查询结果"这条链路后,你就可以把 Figranium 嵌入 CI/CD、定时采集脚本或业务系统,用一行 curl 驱动整个浏览器自动化流水线。

