任务管家 (Scheduler)

使用 Web Scraper API 中免费的任务管家自动化定期爬取任务。用 cron 设置频率、指定任务项和结束时间，并通过专用端点监控运行情况。

任务管家 (Scheduler) 是一个 免费功能 属于网页爬虫API，可让您通过创建计划自动执行定期的爬取和解析任务。

查看下面的视频教程，了解有关任务管家及其工作原理的更多信息。

逐步指南：使用任务管家自动化您的定期爬取任务

我们建议将任务管家与 上传到云存储 (Upload to Cloud Storage) 功能一起使用。这样，您可以设置计划并在存储中定期接收数据更新，而无需尝试从我们的系统获取结果。

重要: 任务管家是一个功能强大的工具，可能会迅速提高您的服务账单。我们建议用少量任务项和有限的重复次数进行测试，以确保您在正确的间隔获得正确的数据。确定无误后，您可以停止测试计划并创建新的、扩展的计划。

快速开始

创建新计划时，请遵循下面的简单步骤。

1. 告诉我们 我们应当多频繁重复这些任务 通过提交 cron 计划表达式；

2. 提供给我们 一组任务参数集合 我们应在计划时间执行；

3. 告知我们 什么时候停止 通过提交结束时间。

参见 此处 以查找提交新计划的代码示例。

注意: 您还可以下载并导入 此 Postman 集合 (this Postman collection) 以试用我们所有的任务管家端点。对 Postman 不熟悉？了解有关此工具的更多信息 此处.

端点

任务管家有几个端点，您可以用来控制该服务：

• 创建新计划

• 获取所有计划

• 获取 运行 信息

• 获取已计划的任务

• 获取计划信息

• 停用或重新激活计划

创建新计划

概览

使用此端点来启动新计划。

• 端点: https://data.oxylabs.io/v1/schedules

• 方法: POST

• 认证: Basic

• 请求头: Content-Type: application/json

输入

参数	描述	默认值
cron	Cron 计划表达式。它决定提交的计划将多频繁运行。阅读更多 此处 和 此处.	-
项目	应作为计划一部分执行的网页爬虫API任务参数集合列表。	-
end_time	计划应停止运行的时间。注意：结束时间是包含性的。	-

- 必需参数

注意: 有关为任务管家有效负载中的 项目 部分整理任务参数集合的指南，请参阅您想使用的特定爬虫的文档页面（例如 Google, Amazon等）。

以下负载将使任务管家在星期一 03:00 运行两个任务计划，直到 end_time （包含）。

{
  "cron": "0 3 * * 1",
  "items": [
    {"source": "universal", "url": "https://ip.oxylabs.io"},
    {"source": "google_search", "query": "stuff"}
  ],
  "end_time": "2032-12-21 12:34:45"
}

输出

下面的响应确认计划已成功创建。

{
    "schedule_id": 4134906379157007223,
    "active": true,
    "items_count": 3,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2022-06-06 10:15:00"
}

获取所有计划

概览

使用此端点可获取与您的用户帐户关联的所有计划列表。

• 端点: https://data.oxylabs.io/v1/schedules

• 方法: GET

• 认证: Basic

输出

此端点返回与发出请求的用户帐户关联的所有计划 ID 列表。

参见下面的示例响应。

{
    "schedules": [
        1764178033254455101,
        2885262175311057587,
        3251365810325795747,
        4134906379157007223,
        4164931482277157062
    ]
}

获取运行信息

概览

使用此端点可获取有关计划中所有运行的列表的信息，以及每个任务和每次运行的元数据与成功率。

• 端点: https://data.oxylabs.io/v1/schedules/{id}/runs

• 方法: GET

• 认证: Basic

输出

下面的负载包含一个示例 /runs 端点响应。

{
 "runs": [
        {
            "run_id": 25037485,
            "jobs": [
                {
                    "id": 7300439540206948353,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:23"
                },
                {
                    "id": 7300439540169188353,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:22"
                },
                {
                    "id": 7300439540198551553,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:23"
                }
            ],
            "success_rate": 1
        }
}

键	描述	类型
运行	表示已计划任务或工作流的执行实例的一组运行对象集合。	数组
运行:run_id	特定运行实例的唯一标识符。	整数
运行:jobs	作为此运行的一部分执行的任务对象集合。	数组
运行:success_rate	此运行中成功任务与总任务的比率（范围 0 到 1）。	数字
运行:jobs:id	该特定任务的 Oxylabs 唯一标识符。	整数
运行:jobs:create_status_code	创建任务时返回的 HTTP 状态码，表示任务请求的初始接受情况。	整数
运行:jobs:result_status	任务的执行状态（例如，"done"、"failed"、"pending"）。	字符串
运行:jobs:created_at	任务创建的时间戳	字符串
运行:jobs:result_created_at	任务完成并生成结果的时间戳	字符串

获取已计划的任务

概览

使用此端点可获取作为运行计划的结果而执行的爬取任务列表。

• 端点: https://data.oxylabs.io/v1/schedules/{id}/jobs

• 方法: GET

• 认证: Basic

输出

下面的负载包含一个示例计划信息响应。

{
    "jobs": [
        7300439540206948353,
        7300439540169188353,
        7300439540198551553,
        ...,
      ]
}

获取计划信息

概览

使用此端点可获取有关特定计划的信息。

• 端点: https://data.oxylabs.io/v1/schedules/{id}

• 方法: GET

• 认证: Basic

输出

下面的负载包含一个示例计划信息响应。

{
    "schedule_id": 1764178033254455101,
    "active": true,
    "items_count": 3,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2022-06-06 10:18:00",
    "links": [
        {
            "rel": "runs",
            "href": "/v1/schedules/1764178033254455101/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/1764178033254455101/jobs",
            "method": "GET"
        }
    ],
    "stats": {
        "total_job_count": 3,
        "job_create_outcomes": [
            {
                "status_code": 202,
                "job_count": 3,
                "ratio": 1
            }
        ],
        "job_result_outcomes": [
            {
                "status": "done",
                "job_count": 2,
                "ratio": 0.67
            },
            {
                "status": "faulted",
                "job_count": 1,
                "ratio": 0.33
            }
        ]
    }
}

键	描述	类型
items_count	计划的唯一 ID。	整数
active	该计划当前是否处于激活状态？	布尔值
与计划关联的 cron 表达式。	total_job_count	整数
cron	计划将停止重复的时间。	字符串
end_time	计划下次运行的时间。	字符串
JSON 对象	next_run_at	字符串
schedule_id	链接集合，定义与计划资源相关的可用 API 端点。	数组
schedule_id:rel	关系标识符，解释该链接相对于父资源的用途。	字符串
schedule_id:href	API 端点的 URL 路径。表示可访问的资源位置。	字符串
schedule_id:method	访问该端点时应使用的 HTTP 方法。	字符串
JSON 数组	计划中的项目（任务）数量。	包含任务创建和任务完成统计信息。
JSON 数组:包含任务创建统计数据。	total_job_count	整数
JSON 数组:stats	尝试执行计划（创建爬取/解析任务）时收到的状态码。	包含作为计划执行的一部分而执行的爬取/解析任务的结果统计。
JSON 数组:stats:导致该特定状态码的任务创建尝试次数。	status_code	整数
JSON 数组:stats:job_count	表示导致特定创建尝试结果的任务创建尝试数量与任务创建尝试总数之间的比率。	整数
JSON 数组:stats:ratio	job_create_outcomes	浮点数
（任务已失败）。	job_result_outcomes	包含作为计划执行的一部分而执行的爬取/解析任务的结果统计。
状态的任务数量。	状态 任务状态。可能的值： pending （任务仍在处理中）， done （任务已成功完成）， faulted	字符串
job_count	导致该特定 状态的任务数量。.	整数
ratio	具有特定状态的任务数量与创建的任务总数之间的比率。	浮点数

停用或重新激活计划

概览

使用此端点可激活或停用特定计划。

• 端点: https://data.oxylabs.io/v1/schedules/{id}/state

• 方法: PUT

• 认证: Basic

输入

使用此端点可停止或重新启动计划。

通过将 active 设置为 false, 您可以停止特定计划的执行。

如果您将 active 设置为 设置为 true, 您可以重新激活先前停止的计划。

{
  "active": false
}

输出

null

标准响应是带有 202 状态码 的空响应体。

API 响应代码

有关 API 响应代码，请参阅 API 部分。