API 轮询

在应用中打开

Agent 设置 → API Poll — 你可以直接在 AnySoul 的设置面板中配置轮询端点。

API 轮询让 Agent 定期从外部 REST API 拉取数据。与接收外部推送的 Webhook 不同，轮询按计划主动拉取数据——由浏览器直接发起 HTTP 请求。

所有配置、凭据和调度全部在浏览器内完成。服务端完全不感知轮询的存在。

工作原理

1. 浏览器的 setInterval 定时器触发
2. 浏览器直接调用外部 API（凭据不经过 AnySoul 服务端）
3. 将响应映射到事件字段（与 Webhook 使用相同的模板引擎）
4. 可选的 SHA-256 diff 检查跳过重复数据
5. 映射结果通过自动创建的 Bridge Webhook 发送到服务端——复用现有的 Webhook ingest 端点，服务端零改动

创建 Poll 端点

1. 打开 Agent 设置 → API Poll
2. 点击 添加
3. 填写：
   • 名称 — 此 poll 的标签（如 tokyo-weather、btc-price）
   • URL — 要调用的 API 端点（支持 http:// 和 localhost）
   • 方法 — GET 或 POST
   • 鉴权 — 参见鉴权模式
   • 间隔 — 轮询频率（1 秒 – 24 小时）
   • JSON Path — 从响应中提取嵌套对象（如 data.items）
   • 去重模式 — Full（每次轮询都创建事件）或 Diff（仅数据变化时创建）
4. 点击 创建

新建的 poll 默认为测试模式。使用 Test Now 验证响应，配置好映射后再正式上线。

测试模式

当 poll 处于测试模式时：

1. 在 poll 卡片上点击 Test Now
2. 浏览器调用外部 API 并显示原始响应
3. 打开映射对话框，配置响应到事件字段的映射
4. 查看实时预览
5. 点击正式上线激活——轮询定时器启动，每次成功轮询都会创建事件

测试模式让你可以反复调整配置，而不会创建事件。

localhost 天然可达

轮询在浏览器中运行，因此 http://localhost 和局域网地址天然可达。非常适合 Home Assistant、NAS API、本地开发服务器等内部服务。

鉴权模式

模式	Header / 参数	适用场景
None	—	公开 API、localhost 服务
Bearer Token	Authorization: Bearer <token>	使用 OAuth 令牌或静态 Bearer 令牌的 API
API Key (Header)	自定义 header（如 X-API-Key）	需要在特定 header 中传 key 的 API
API Key (Query)	Query 参数（如 ?appid=xxx）	像 OpenWeatherMap 这样使用查询字符串传 key 的 API

所有凭据存储在 IndexedDB 中，永远不离开浏览器。

警告

凭据以明文存储在 IndexedDB 中——与 BYOK API key 在 localStorage 中的安全模型一致。清除浏览器数据会删除 poll 配置。请使用导出进行备份。

可视化映射

映射对话框与 Webhook 的映射编辑器完全相同：

• 左侧面板 — 测试响应的 JSON 树。点击字段可自动插入映射表达式。
• 右侧面板 — 5 个目标字段：

字段	键	必填	示例
Platform	platform	否	api-poll
Element	element	否	weather
Event Type	event_type	否	update
Title	title	是	{{ payload.weather.0.description }} — {{ payload.main.temp }}°C
Payload	payload	否	{{ payload.main }}

模板语法通用——参见模板语法。

Agent 看到的内容

轮询事件在 Agent 事件流中的显示与 Webhook 事件完全一致：

- [02-22 09:00] [evt_xyz789] api-poll/weather (update): scattered clouds — 12.5°C

Agent 不区分推送和拉取——它只是看到一个新事件。

响应配置

JSON Path

使用 JSON Path 在映射前从 API 响应中提取嵌套值。例如，响应为：

{
  "status": "ok",
  "data": {
    "temperature": 12.5,
    "humidity": 80
  }
}

将 JSON Path 设为 data，则提取 { "temperature": 12.5, "humidity": 80 } 作为映射输入。

留空则使用整个响应对象。

去重模式

模式	行为
Full	每次成功轮询都创建事件
Diff	将映射结果的 SHA-256 哈希与上次轮询比较。仅在映射输出变化时创建事件。

Diff 模式适用于大部分时间返回相同数据的 API（如天气、系统状态）。由于哈希是基于映射结果计算的，未映射的字段（如时间戳、请求 ID）发生变化时不会触发重复事件。

Endpoint 生命周期

状态流转

状态	标签颜色	行为
测试中	琥珀色	Test Now 可用，定时器未启动，不创建事件
已激活	绿色	定时器按计划运行，每次成功轮询创建事件
已禁用	灰色	定时器停止，不发送请求

可用的状态转换：

• 测试中 → 正式上线（已激活）或禁用
• 已激活 → 暂停（已禁用）或测试模式（测试中）
• 已禁用 → 启用（已激活）

连续失败自动禁用

如果 poll 连续失败 5 次，将自动禁用。poll 卡片上会显示错误信息。修复问题（URL、凭据、CORS）后手动重新启用。

CORS 注意事项

由于请求从浏览器发起，受 CORS 策略限制：

目标	CORS 行为	状况
localhost / 局域网	通常无 CORS 限制	可用
公开 API（CoinGecko、OpenWeatherMap 等）	多数设置 Access-Control-Allow-Origin: *	通常可用
受限 API	可能阻止浏览器请求	可能不可用

当 Test Now 请求因 CORS 失败时，错误信息会明确提示。解决方案：

1. 改用 Webhook — 如果 API 支持 Webhook 回调
2. 使用 CORS 代理 — 添加 CORS header 的轻量本地代理
3. 浏览器扩展 — 扩展不受 CORS 限制

导入 / 导出

Poll 配置可导出为 JSON，并在其他设备或浏览器上导入。

• 导出：下载包含当前 Agent 所有 poll 配置的 JSON 文件。运行时状态（最后轮询时间、错误）被去除，凭据被保留。
• 导入：读取 JSON 文件并创建新的 poll 条目。导入的 poll 以测试模式开始。已有的 poll 不会被覆盖。

警告

导出文件包含明文凭据。请妥善保管。

限制

限制	值
最小轮询间隔	1 秒
最大轮询间隔	86400 秒（24 小时）
每个 Agent 最大 poll 数	10
请求超时	10 秒
最大响应大小（映射用）	50 KB
最大事件 payload 大小	10 KB

Webhook 与 API Poll 对比

	Webhook（推送）	API Poll（拉取）
方向	外部 → 服务端	浏览器 → 外部 → 浏览器 → 服务端
触发	外部系统发送 POST	浏览器定时器（setInterval）
运行条件	服务端运行中（始终）	浏览器/Electron 处于打开状态
配置存储	服务端（D1 数据库）	浏览器（IndexedDB）
凭据	服务端验证来源	浏览器发送到外部 API
localhost	不可达	天然可达
跨设备	自动同步	导入/导出 JSON
映射	相同模板引擎	相同模板引擎
服务端改动	Webhook 表 + 路由	无

相关

• Webhook — 推送式事件接入
• 事件流概念