排程任務

使用基於 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"
}