任务调度器

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

Scheduler 是一个 免费功能 Web Scraper API 的一项功能，允许您通过创建计划来自动化定期的抓取和解析任务。

查看下面的视频教程以了解有关任务调度器及其工作原理的更多信息。

使用任务调度器自动化定期抓取任务的逐步指南

我们建议将任务调度器与 上传到云存储 功能一起使用。通过这种方式，您可以设置计划并在存储中定期接收数据更新，而无需尝试从我们的系统获取结果。

重要: 任务调度器是一个强大的工具，可能会迅速增加您的服务费用。我们建议先用少量任务项和有限的重复次数进行测试，以确保您能在正确的间隔获取正确的数据。确认无误后，您可以停止测试计划并创建新的、扩大规模的计划。

快速入门

创建新计划时，请按照以下简单步骤操作。

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

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

3. 让我们知道 何时停止 通过提交结束时间。

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

注意：您也可以下载并导入 此 Postman 集合 以试用我们所有的 Scheduler 端点。首次使用 Postman？了解有关此工具的更多信息 此处.

端点

Scheduler 有几个可用于控制服务的端点：

• 创建新计划

• 获取所有计划

• 获取 运行 信息

• 获取已计划的作业

• 获取计划信息

• 停用或重新激活计划

创建新计划

概览

使用此端点启动新计划。

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

• 方法: POST

• 身份验证: 基础

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

输入

参数	说明	默认值
cron	Cron 计划表达式。它决定提交的计划将多久运行一次。阅读更多 此处 和 此处.	-
items	应作为计划一部分执行的一组 Scraper APIs 作业参数集的列表。	-
end_time	计划应停止运行的时间。注：结束时间包含在内。	-

- 必填参数

注意：有关为调度器有效负载中的 items 部分组装作业参数集的指导，请参阅您希望使用的特定爬虫的文档页面（例如 Google, Amazon，等）。

下面的有效负载将使 Scheduler 在周一 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

• 身份验证: 基础

输出

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

参见下面的示例响应。

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

获取运行信息

概览

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

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

• 方法: GET

• 身份验证: 基础

输出

下面的有效负载包含一个示例 /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
        }
}

键	说明	类型
运行	一组运行对象，表示已计划任务或工作流的执行实例。	Array
运行:run_id	特定运行实例的唯一标识符。	整数
运行:jobs	作为此运行的一部分执行的作业对象集合。	Array
运行: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

• 身份验证: 基础

输出

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

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

获取计划信息

概览

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

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

• 方法: GET

• 身份验证: 基础

输出

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

{
    "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": "完成",
                "job_count": 2,
                "ratio": 0.67
            },
            {
                "status": "faulted",
                "job_count": 1,
                "ratio": 0.33
            }
        ]
    }
}

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

停用或重新激活计划

概览

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

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

• 方法: PUT

• 身份验证: 基础

输入

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

通过设置 active to false，您可以停止特定计划的执行。

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

{
  "active": false
}

输出

null

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

API 响应代码

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