定时任务

使用基于 cron 的调度功能自动化执行周期性的抓取、爬取和搜索操作。

简介

定时任务允许您使用标准 cron 表达式自动化执行周期性的网页抓取、爬取和数据采集操作。非常适合用于监控网站、跟踪价格变化、归档内容、聚合搜索结果或任何需要定期采集数据的场景。

核心特性：支持 cron 调度和时区设置、多种并发模式、自动失败处理、积分管理以及 Webhook 集成，用于事件通知。

核心功能

Cron 表达式调度：使用标准 cron 语法定义执行计划
时区支持：在任意时区执行任务（例如 Asia/Shanghai、America/New_York）
并发控制：两种模式 - 跳过或排队并发执行
自动暂停：连续失败后自动暂停以保护资源
积分管理：每日执行限制和预估积分跟踪
执行历史：跟踪所有执行记录，包含详细状态和指标
Webhook 集成：接收任务事件的实时通知

API 端点

POST   /v1/scheduled-tasks              # 创建定时任务
GET    /v1/scheduled-tasks              # 列出所有任务
GET    /v1/scheduled-tasks/:taskId      # 获取任务详情
PUT    /v1/scheduled-tasks/:taskId      # 更新任务
PATCH  /v1/scheduled-tasks/:taskId/pause   # 暂停任务
PATCH  /v1/scheduled-tasks/:taskId/resume  # 恢复任务
DELETE /v1/scheduled-tasks/:taskId      # 删除任务
GET    /v1/scheduled-tasks/:taskId/executions  # 获取执行历史
DELETE /v1/scheduled-tasks/:taskId/executions/:executionId  # 取消执行

快速开始

创建每日抓取任务

curl -X POST "https://api.anycrawl.dev/v1/scheduled-tasks" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Tech News",
    "description": "Scrape Hacker News daily at 9 AM",
    "cron_expression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "task_type": "scrape",
    "task_payload": {
      "url": "https://news.ycombinator.com",
      "engine": "cheerio",
      "formats": ["markdown"]
    },
    "concurrency_mode": "skip",
    "max_executions_per_day": 1
  }'

响应

{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "next_execution_at": "2026-01-28T01:00:00.000Z"
  }
}

Cron 表达式指南

Cron 表达式使用 5 个字段来定义调度计划：

* * * * *
│ │ │ │ │
│ │ │ │ └─ 星期几 (0-7, 0 和 7 = 星期日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)

常见示例

表达式	说明	执行时间
`0 9 * * *`	每天上午 9:00	每日 09:00:00
`/15 * * *`	每 15 分钟	:00, :15, :30, :45
`0 /6 * *`	每 6 小时	00:00, 06:00, 12:00, 18:00
`0 9 * * 1`	每周一上午 9 点	周一 09:00:00
`0 0 1 * *`	每月第一天	每月 1 日 00:00:00
`30 2 * * 0`	每周日凌晨 2:30	周日 02:30:00

使用 crontab.guru 来验证和理解 cron 表达式。

请求参数

任务配置

参数	类型	必填	默认值	说明
`name`	string	是	-	任务名称（1-255 个字符）
`description`	string	否	-	任务描述
`cron_expression`	string	是	-	标准 cron 表达式（5 个字段）
`timezone`	string	否	`"UTC"`	执行时区（例如 "Asia/Shanghai"）
`task_type`	string	是	-	任务类型：`"scrape"`、`"crawl"`、`"search"` 或 `"template"`
`task_payload`	object	是	-	任务配置（见下文）

并发控制

参数	类型	必填	默认值	说明
`concurrency_mode`	string	否	`"skip"`	模式：`"skip"` 或 `"queue"`
`max_executions_per_day`	number	否	-	每日执行限制

执行元数据（只读）

这些字段在任务响应中返回，不接受在创建/更新请求体中传入：

min_credits_required：单次执行的预估最低积分（由服务器计算）
consecutive_failures：用于自动暂停的连续失败计数

Webhook 集成

参数	类型	必填	默认值	说明
`webhook_ids`	string[]	否	-	要触发的 Webhook 订阅 UUID 数组
`webhook_url`	string	否	-	直接 Webhook URL（创建隐式订阅）

您可以使用 webhook_ids 引用已有的 Webhook 订阅，或提供 webhook_url 为此任务创建隐式 Webhook 订阅。

元数据

参数	类型	必填	默认值	说明
`tags`	string[]	否	-	用于组织的标签
`metadata`	object	否	-	自定义元数据

任务负载

抓取任务

{
  "url": "https://example.com/page",
  "engine": "cheerio",
  "formats": ["markdown"],
  "timeout": 60000,
  "wait_for": 2000,
  "include_tags": ["article", "main"],
  "exclude_tags": ["nav", "footer"]
}

爬取任务

{
  "url": "https://example.com",
  "engine": "playwright",
  "options": {
    "max_depth": 3,
    "limit": 50,
    "strategy": "same-domain",
    "exclude_paths": ["/admin/*", "/api/*"],
    "scrape_options": {
      "formats": ["markdown"]
    }
  }
}

搜索任务

{
  "query": "artificial intelligence news",
  "engine": "google",
  "limit": 20,
  "country": "US",
  "lang": "en",
  "timeRange": "day"
}

模板任务

{
  "template_id": "my-search-template",
  "query": "machine learning tutorials",
  "variables": {
    "lang": "en"
  }
}

对于 task_type: "template"，task_payload 必须包含：

template_id（必填）：要执行的模板
该模板类型所需的端点特定输入字段（例如抓取/爬取模板的 url，搜索模板的 query）
可选的 variables 用于传递动态模板输入

并发模式

skip（推荐）

如果上一次执行仍在运行，则跳过当前执行。

适用于：执行时间可能超过执行间隔的任务。

示例：每小时调度的爬取任务，有时需要 90 分钟完成。

queue

将新执行加入队列，等待上一次执行完成。

适用于：每次执行都必须执行、不能跳过的任务。

示例：不能遗漏任何调度执行的关键数据采集任务。

管理任务

列出所有任务

curl -X GET "https://api.anycrawl.dev/v1/scheduled-tasks" \
  -H "Authorization: Bearer <your-api-key>"

响应

{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Daily Tech News",
      "task_type": "scrape",
      "cron_expression": "0 9 * * *",
      "timezone": "Asia/Shanghai",
      "is_active": true,
      "is_paused": false,
      "next_execution_at": "2026-01-28T01:00:00.000Z",
      "total_executions": 45,
      "successful_executions": 43,
      "failed_executions": 2,
      "consecutive_failures": 0,
      "last_execution_at": "2026-01-27T01:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

暂停任务

暂停任务以临时停止其执行。reason 参数将作为 pause_reason 存储在任务记录中。

curl -X PATCH "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/pause" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Maintenance period"
  }'

响应

{
  "success": true,
  "message": "Task paused successfully",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "is_paused": true,
    "pause_reason": "Maintenance period"
  }
}

恢复任务

curl -X PATCH "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/resume" \
  -H "Authorization: Bearer <your-api-key>"

更新任务

curl -X PUT "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "cron_expression": "0 10 * * *",
    "description": "Updated description"
  }'

响应

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Daily Tech News",
    "description": "Updated description",
    "task_type": "scrape",
    "cron_expression": "0 10 * * *",
    "timezone": "Asia/Shanghai",
    "task_payload": {
      "url": "https://news.ycombinator.com",
      "engine": "cheerio",
      "formats": ["markdown"]
    },
    "concurrency_mode": "skip",
    "is_active": true,
    "is_paused": false,
    "next_execution_at": "2026-01-28T02:00:00.000Z",
    "total_executions": 45,
    "successful_executions": 43,
    "failed_executions": 2,
    "consecutive_failures": 0,
    "last_execution_at": "2026-01-27T01:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-27T12:00:00.000Z",
    "icon": "FileText"
  }
}

只需包含您要更新的字段，其他字段将保持不变。

删除任务

curl -X DELETE "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId" \
  -H "Authorization: Bearer <your-api-key>"

删除任务也会删除其所有执行历史。

执行历史

获取执行记录

curl -X GET "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/executions?limit=20" \
  -H "Authorization: Bearer <your-api-key>"

响应

{
  "success": true,
  "data": [
    {
      "uuid": "exec-uuid-1",
      "scheduled_task_uuid": "task-uuid",
      "execution_number": 45,
      "status": "completed",
      "started_at": "2026-01-27T01:00:00.000Z",
      "completed_at": "2026-01-27T01:02:15.000Z",
      "duration_ms": 135000,
      "job_uuid": "job-uuid-1",
      "triggered_by": "scheduler",
      "scheduled_for": "2026-01-27T01:00:00.000Z",
      "error_message": null,
      "credits_used": 5,
      "items_processed": 1,
      "items_succeeded": 1,
      "items_failed": 0,
      "job_status": "completed",
      "job_success": true,
      "icon": "CircleCheck"
    }
  ]
}

注意： credits_used、items_processed、items_succeeded、items_failed、job_status 和 job_success 字段通过 JOIN 从关联的作业记录中获取。duration_ms 由 started_at 和 completed_at 计算得出。

取消执行

取消当前处于待执行或运行中状态的单次执行。当您需要停止特定执行而不暂停整个任务时，此功能非常有用。

curl -X DELETE "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/executions/:executionId" \
  -H "Authorization: Bearer <your-api-key>"

响应

{
  "success": true,
  "message": "Execution cancelled successfully"
}

只有状态为 pending 或 running 的执行才能被取消。已完成、已失败或已取消的执行将返回错误。

自动失败处理

连续失败自动暂停

任务在连续 5 次失败后会自动暂停，以防止资源浪费和过多的 API 调用。

恢复：在修复根本问题后手动恢复任务。

curl -X PATCH "https://api.anycrawl.dev/v1/scheduled-tasks/:taskId/resume" \
  -H "Authorization: Bearer <your-api-key>"

监控失败

通过任务状态中的 consecutive_failures 字段跟踪失败情况：

{
  "consecutive_failures": 3,
  "failed_executions": 5,
  "successful_executions": 40
}

监控 consecutive_failures 字段。较高的值表明存在需要关注的反复出现的问题。

与 Webhook 集成

使用 Webhook 订阅任务事件：

curl -X POST "https://api.anycrawl.dev/v1/webhooks" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Task Notifications",
    "webhook_url": "https://your-domain.com/webhook",
    "event_types": ["task.executed", "task.failed", "task.paused"],
    "scope": "all"
  }'

详情请参阅 Webhooks。

常见用例

价格监控

每小时监控产品价格：

{
  "name": "Hourly Price Tracker",
  "cron_expression": "0 * * * *",
  "task_type": "scrape",
  "task_payload": {
    "url": "https://shop.example.com/product/12345",
    "engine": "cheerio",
    "formats": ["markdown"]
  },
  "concurrency_mode": "skip"
}

每周文档备份

每周爬取并归档文档：

{
  "name": "Weekly Docs Backup",
  "cron_expression": "0 3 * * 0",
  "timezone": "UTC",
  "task_type": "crawl",
  "task_payload": {
    "url": "https://docs.example.com",
    "engine": "playwright",
    "options": {
      "max_depth": 10,
      "limit": 500
    }
  },
  "max_executions_per_day": 1
}

每日新闻聚合

每天抓取多个新闻来源：

{
  "name": "Morning News Digest",
  "cron_expression": "0 6 * * *",
  "timezone": "America/New_York",
  "task_type": "scrape",
  "task_payload": {
    "url": "https://news.example.com",
    "engine": "cheerio",
    "formats": ["markdown"]
  },
  "max_executions_per_day": 1
}

竞争情报

每小时跟踪竞争对手提及和行业趋势：

{
  "name": "Competitor Monitoring",
  "cron_expression": "0 * * * *",
  "task_type": "search",
  "task_payload": {
    "query": "YourCompany OR CompetitorA OR CompetitorB",
    "engine": "google",
    "limit": 50,
    "timeRange": "day"
  },
  "concurrency_mode": "skip"
}