任务管家

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

任务管家 是一个 免费功能 网页爬虫API 的功能，可让你通过创建计划来自动化重复性的抓取和解析任务。

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

使用任务管家自动化你的重复抓取任务的分步指南

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

重要: 任务管家是一个强大的工具，可能会快速增加你的服务账单。我们建议先用少量任务项和有限次数的重复进行测试，以确保你在正确的时间间隔获得正确的数据。一旦确认无误，你就可以停止测试计划，并创建一个放大后的新计划。

快速开始

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

1. 告诉我们 我们应该多久重复执行一次任务 通过提交 cron 计划表达式；
2. 提供给我们 一组任务参数集 我们应在计划时间执行这些参数；
3. 告知我们 何时停止 通过提交结束时间。

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

注意：你也可以下载并导入 此 Postman 集合 来试用我们所有的任务管家端点。Postman 新手？了解更多关于这个工具 此处.

端点

任务管家提供多个可用于控制服务的端点：

• 创建新计划
• 获取所有计划
• 获取 运行 信息
• 获取计划任务
• 获取计划信息
• 停用或重新激活计划

创建新计划

概述

使用此端点启动新计划。

• 端点: https://data.oxylabs.io/v1/schedules
• 方法: POST
• Authentication: 基础
• 请求头: Content-Type: application/json

输入

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

- 必填参数

注意：关于为 items 任务管家负载中的这部分组装任务参数集的指导，请参考你想使用的特定爬虫的文档页面（例如 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
• Authentication: 基础

输出

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

请参见下面的示例响应。

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

获取运行信息

概述

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

• 端点: https://data.oxylabs.io/v1/schedules/{id}/runs
• 方法: GET
• Authentication: 基础

输出

下面的负载包含一个示例 /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
• Authentication: 基础

输出

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

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

获取计划信息

概述

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

• 端点: https://data.oxylabs.io/v1/schedules/{id}
• 方法: GET
• Authentication: 基础

输出

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

{
    "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
            }
        ]
    }
}

键	说明	类型
schedule_id	计划的唯一 ID。	整数
active	计划现在是否处于活动状态？	布尔值
items_count	计划中的项目（任务）数量。	整数
cron	与计划关联的 cron 表达式。	字符串
end_time	计划停止重复执行的时间。	字符串
next_run_at	计划下次运行的时间。	字符串
链接	一组链接对象，定义与计划资源相关的可用 API 端点。	数组
链接: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
• Authentication: 基础

输入

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

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

如果你设置 active 到 true，你可以重新激活之前已停止的计划。

{
  "active": false
}

输出

null

标准响应是一个空响应体，带有 202 状态码。

API 响应码

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