> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-scraper-api/features/scheduler.md).

# 任务管家

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

[**任务管家**](https://oxylabs.io/features/scheduler) 是一个 **免费功能** 网页爬虫API中的一项功能，可通过创建计划自动执行重复的抓取和解析任务。

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

{% embed url="<https://www.youtube.com/watch?v=HJLkFZ_9Z5w>" %}
使用任务管家自动化重复抓取任务的分步指南
{% endembed %}

我们建议将任务管家与 [**上传到云存储**](https://developers.oxylabs.io/products/cn/web-scraper-api/features/result-processing-and-storage/cloud-storage.md) 功能一起使用。这样，你可以设置计划，并直接在存储中定期接收数据更新，而无需尝试从我们的系统获取结果。

{% hint style="warning" %}
**重要**: 任务管家是一个功能强大的工具，可能会迅速增加你的服务账单。我们建议先用少量任务项和有限的重复次数进行测试，以确保你能在正确的间隔获得正确的数据。确认无误后，你可以停止测试计划，并创建一个新的、扩展后的计划。
{% endhint %}

## 快速开始

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

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

参见 [**这里**](#create-a-new-schedule) 以查找提交新计划的代码示例。

{% hint style="info" %}
**注意**: 你还可以下载并导入 [**这个 Postman 集合**](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiwDdoZGfMbUe5cRL2417%2Fuploads%2FsipIxRVxZmZroadwSuqg%2FScheduler.postman_collection.json?alt=media\&token=dac92525-e5cc-43c2-a8eb-a32e8eba0483) 来试用我们所有的任务管家端点。刚接触 Postman？了解更多关于这个工具的信息 [**这里**](https://developers.oxylabs.io/integrations/cn/web-scraper-api-integrations/postman.md).
{% endhint %}

## 端点

任务管家有多个端点可用于控制服务：

* [**创建新计划**](#1.-create-a-new-schedule)
* [**获取所有计划**](#get-all-schedules)
* [**获取** **运行** **信息**](#get-runs-information)
* [**获取计划任务**](#get-scheduled-jobs)
* [**获取计划信息**](#get-schedule-info)
* [**停用或重新激活计划**](#change-schedule-state)

### 创建新计划

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules`
* **方法**: `POST`
* **身份验证**: `基础`
* **请求头**: `Content-Type: application/json`

**输入**

<table><thead><tr><th width="125">参数</th><th width="477.3333333333333">说明</th><th>默认值</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><strong><code>cron</code></strong></mark></td><td>Cron 计划表达式。它决定提交的计划运行频率。了解更多 <a href="https://crontab.guru/"><strong>这里</strong></a> 和 <a href="https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm"><strong>这里</strong></a>.</td><td>-</td></tr><tr><td><mark style="background-color:green;"><strong><code>items</code></strong></mark></td><td>作为计划一部分应执行的网页爬虫API任务参数集列表。</td><td>-</td></tr><tr><td><mark style="background-color:green;"><strong><code>end_time</code></strong></mark></td><td>计划应停止运行的时间。注意：结束时间包含在内。</td><td>-</td></tr></tbody></table>

\- 必填参数

{% hint style="info" %}
**注意**：如需了解如何为 **`items`** 你的任务管家载荷构建任务参数集，请参阅你想使用的特定抓取器文档页面（例如 [**谷歌**](https://developers.oxylabs.io/api-targets/cn/search-engines/google), [**亚马逊**](https://developers.oxylabs.io/api-targets/cn/e-commerce/amazon)等）。
{% endhint %}

下面的载荷将使任务管家在每周一 03:00 运行两个任务，直到 `end_time` （包含该时间）。

```json
{
  "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"
}
```

#### 输出

下面的响应确认计划已成功创建。它包括 `items_count` （你提交的任务参数集数量）、首次运行时间，以及指向新计划的 `运行` 和 `任务` 端点的链接。

```json
{
    "schedule_id": 168110763619310929,
    "active": true,
    "items_count": 2,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2026-09-21 03:00:00",
    "links": [
        {
            "rel": "runs",
            "href": "/v1/schedules/168110763619310929/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/168110763619310929/jobs",
            "method": "GET"
        }
    ]
}
```

### 获取所有计划

#### 概览

使用此端点获取与你的用户账户关联的所有计划列表。

* **端点**: `https://data.oxylabs.io/v1/schedules`
* **方法**: `GET`
* **身份验证**: `基础`

#### 输出

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

请参阅下面的示例响应。计划 ID 以字符串形式返回。

```json
{
    "schedules": [
        "168110763619310929",
        "195963006349271396",
        "1192925426751182410",
        "2482057452528425703"
    ]
}
```

### 获取运行信息

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}/runs`
* **方法**: `GET`
* **身份验证**: `基础`

#### 输出

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

```json
{
    "runs": [
        {
            "run_id": 105302280,
            "jobs": [
                {
                    "id": 7505291047442843649,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2026-09-14 15:47:07",
                    "result_created_at": "2026-09-14 15:47:09"
                }
            ],
            "success_rate": 1.0
        },
        {
            "run_id": 105302283,
            "jobs": [
                {
                    "id": 7505291294688676865,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2026-09-14 15:48:06",
                    "result_created_at": "2026-09-14 15:48:07"
                }
            ],
            "success_rate": 1.0
        }
    ]
}
```

<table><thead><tr><th width="216">键</th><th>说明</th><th>类型</th></tr></thead><tbody><tr><td><code>运行</code></td><td>表示计划任务或工作流执行实例的运行对象集合。</td><td>数组</td></tr><tr><td><code>运行</code>:<code>run_id</code></td><td>特定运行实例的唯一标识符。</td><td>整数</td></tr><tr><td><code>运行</code>:<code>任务</code></td><td>作为此次运行一部分执行的任务对象集合。</td><td>数组</td></tr><tr><td><code>运行</code>:<code>success_rate</code></td><td>此次运行中成功任务数与任务总数的比例（范围为 0 到 1）。</td><td>数字</td></tr><tr><td><code>运行</code>:<code>任务</code>:<code>id</code></td><td>特定任务的唯一 Oxylabs 标识符。</td><td>整数</td></tr><tr><td><code>运行</code>:<code>任务</code>:<code>create_status_code</code></td><td>任务创建时返回的 HTTP 状态码，表示已初步接受该任务请求。</td><td>整数</td></tr><tr><td><code>运行</code>:<code>任务</code>:<code>result_status</code></td><td>任务的执行状态： <code>pending</code>, <code>完成</code> 或 <code>faulted</code>.</td><td>字符串</td></tr><tr><td><code>运行</code>:<code>任务</code>:<code>created_at</code></td><td>任务创建时间戳</td><td>字符串</td></tr><tr><td><code>运行</code>:<code>任务</code>:<code>result_created_at</code></td><td>任务完成并生成结果的时间戳</td><td>字符串</td></tr></tbody></table>

### 获取计划任务

#### 概览

使用此端点获取因运行计划而执行的抓取任务列表。

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}/jobs`
* **方法**: `GET`
* **身份验证**: `基础`

#### 输出

下面的载荷包含一个示例响应：该计划迄今创建的所有任务 ID。

```json
{
    "jobs": [
        7505291047442843649,
        7505291294688676865
    ]
}
```

### 获取计划信息

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}`
* **方法**: `GET`
* **身份验证**: `基础`

#### 输出

下面的载荷包含一个示例计划信息响应。在第一次运行之前， `stats` 是一个空对象。

```json
{
    "schedule_id": 485005153871537982,
    "active": true,
    "items_count": 2,
    "cron": "26 8 * * *",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2026-09-16 08:26:00",
    "links": [
        {
            "rel": "runs",
            "href": "/v1/schedules/485005153871537982/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/485005153871537982/jobs",
            "method": "GET"
        }
    ],
    "stats": {
        "total_job_count": 2,
        "job_create_outcomes": [
            {
                "status_code": 202,
                "job_count": 2,
                "ratio": 1.0
            }
        ],
        "job_result_outcomes": [
            {
                "status": "done",
                "job_count": 2,
                "ratio": 1.0
            }
        ]
    }
}
```

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

### 停用或重新激活计划

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}/state`
* **方法**: `PUT`
* **身份验证**: `基础`

#### 输入

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

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

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

```json
{
  "active": false
}
```

**输出**

```json
null
```

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

## API 响应代码

有关 API 响应代码，请参阅 [**API**](https://developers.oxylabs.io/products/cn/web-scraper-api/response-codes.md#api) 部分。缺少或无效参数的计划请求将被 HTTP `422` 以及一个 `detail` 列表中会标明该字段；未知的计划 ID 将返回 HTTP `404`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-scraper-api/features/scheduler.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
