监控（Monitors）

按计划追踪网页与价格变化，支持 diff 检测、AI 过滤，以及 Webhook 或邮件告警。

简介

Monitors（监控）用于持续追踪 URL 的变化。每个 monitor 按 cron 计划执行抓取，将结果与上一快照对比，并在检测到有意义的变化时发送通知。

核心能力：网页文本 diff、结构化价格提取、可选 AI 判断、Webhook/邮件通知、快照历史、按需立即检查。

监控类型

类型	`monitor_type`	默认 `track_mode`	适用场景
网页	`"webpage"`	`"text"`	文档、博客、服务条款、状态页
价格	`"price"`	`"json"`	商品价格、库存、结构化字段

Monitor 基于定时任务（Scheduled Tasks）实现。创建 monitor 时会自动创建一条 1:1 关联的后台 scrape 定时任务，调度由 monitor API 统一管理。

MVP 说明： 请求体可包含多个 targets，但当前仅对 第一个 target 创建调度。多 target 支持将在后续版本提供。

API 端点

POST   /v1/monitors                         # 创建 monitor
GET    /v1/monitors                         # 列出 monitors
GET    /v1/monitors/:id                     # 获取详情
PATCH  /v1/monitors/:id                     # 更新
DELETE /v1/monitors/:id                     # 删除
POST   /v1/monitors/:id/pause                 # 暂停
POST   /v1/monitors/:id/resume                # 恢复
POST   /v1/monitors/:id/check                 # 立即触发检查
GET    /v1/monitors/:id/snapshots             # 快照列表
GET    /v1/monitors/:id/changes               # 变更列表
GET    /v1/monitors/:id/changes/:changeId     # 变更详情

快速开始

网页变更监控

每小时检查文档页，变更时通过 Webhook 告警：

curl -X POST "https://api.anycrawl.dev/v1/monitors" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "文档更新监控",
    "monitor_type": "webpage",
    "cron_expression": "0 * * * *",
    "timezone": "Asia/Shanghai",
    "targets": [
      {
        "url": "https://example.com/changelog",
        "engine": "auto"
      }
    ],
    "diff_options": {
      "only_main_content": true,
      "min_change_ratio": 0.01
    },
    "notify_options": {
      "channels": ["webhook"],
      "only_meaningful": true
    }
  }'

响应示例

{
  "success": true,
  "data": {
    "monitor_id": "550e8400-e29b-41d4-a716-446655440000",
    "scheduled_task_id": "660e8400-e29b-41d4-a716-446655440001",
    "track_mode": "text",
    "next_execution_at": "2026-07-17T13:00:00.000Z"
  }
}

价格监控

每 15 分钟提取并对比商品价格：

{
  "name": "商品价格追踪",
  "monitor_type": "price",
  "cron_expression": "*/15 * * * *",
  "targets": [
    { "url": "https://shop.example.com/product/12345", "engine": "auto" }
  ],
  "extract_schema": {
    "type": "object",
    "properties": {
      "price": { "type": "number" },
      "currency": { "type": "string" },
      "in_stock": { "type": "boolean" }
    },
    "required": ["price"]
  },
  "notify_options": {
    "channels": ["webhook"],
    "thresholds": { "price_change_pct": 5 }
  }
}

当 monitor_type 为 "price" 时，必须提供 extract_schema。

请求参数

核心配置

参数	类型	必填	默认值	说明
`name`	string	是	-	名称（1–255 字符）
`monitor_type`	string	否	`"webpage"`	`"webpage"` 或 `"price"`
`cron_expression`	string	是	-	标准 5 段 cron
`timezone`	string	否	`"UTC"`	时区
`targets`	array	是	-	监控目标 URL 列表
`goal`	string	否	-	AI 判断用的自然语言目标
`track_mode`	string	否	自动推断	`"text"` / `"json"` / `"mixed"`
`extract_schema`	object	条件必填	-	结构化提取 schema（price 必填）

diff_options

参数	说明
`only_main_content`	仅对比正文，默认 `true`
`ignore_selectors`	忽略的 CSS 选择器
`min_change_ratio`	最小变更比例（0–1）

notify_options

参数	说明
`channels`	`"webhook"` 和/或 `"email"`
`email_recipients`	启用 email 时必填
`only_meaningful`	过滤噪声，默认 `true`
`thresholds.price_change_pct`	价格变更百分比阈值

邮件通知需在自托管环境中配置 ANYCRAWL_SMTP_*，详见 Docker 部署。

变更检测流程

抓取 — 后台定时任务执行 scrape
标准化 — 提取正文、应用 selector 过滤
快照 — 存储内容与 hash
Diff — 文本 diff 或 JSON 字段对比
判断 — 设置 goal 时由 AI 过滤噪声
通知 — 发送 Webhook 或邮件

管理 Monitor

// 生命周期
await client.pauseMonitor(monitorId);
await client.resumeMonitor(monitorId);
await client.runMonitor(monitorId); // 立即检查

// 历史
const snapshots = await client.getMonitorSnapshots(monitorId, { limit: 20 });
const changes = await client.getMonitorChanges(monitorId, { limit: 20 });
const detail = await client.getMonitorChange(monitorId, changeId);

立即检查返回 202；若已有检查进行中则返回 409。

Webhook 事件

通过 Webhooks 订阅：

事件	说明
`monitor.check.completed`	检查完成（含摘要）
`monitor.changed`	网页内容有意义变更
`monitor.price.changed`	价格或结构化字段变更
`monitor.error`	检查失败

Payload 内联 diff 数据，无需额外请求 changes API。

JavaScript SDK

安装 0.0.6+ 版本：

pnpm add @anycrawl/js-sdk

完整 API 见英文文档 Monitors 或 SDK README。

限制

项	限制
实际调度的 target 数	1（MVP 仅首个）
请求体 targets 上限	50
邮件收件人	20
内联快照大小	默认 256 KB（`ANYCRAWL_MONITOR_MAX_INLINE_CHARS`）

简介