> 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 %}

我们建议将任务管家与 [**上传到云存储**](/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？了解更多关于此工具 [**这里**](/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`
* **认证**: `Basic`
* **请求头**: `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>条目</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" %}
**注**：关于如何组合作业参数集的指导，请参阅 **`条目`** 任务管家负载的这部分，请参考你想使用的具体爬虫的文档页面（例如 [**Google**](/api-targets/cn/search-engines/google.md), [**Amazon**](/api-targets/cn/e-commerce/amazon.md)等）。
{% 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` （你提交的作业参数集数量）、首次运行时间，以及指向新计划 `运行` 和 `jobs` 端点的链接。

```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`
* **认证**: `Basic`

#### 输出

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

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

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

### 获取运行信息

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}/runs`
* **方法**: `GET`
* **认证**: `Basic`

#### 输出

下面的负载包含一个示例 `/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>jobs</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>jobs</code>:<code>id</code></td><td>特定作业的唯一 Oxylabs 标识符。</td><td>整数</td></tr><tr><td><code>运行</code>:<code>jobs</code>:<code>create_status_code</code></td><td>作业创建时返回的 HTTP 状态码，表示已初步接受该作业请求。</td><td>整数</td></tr><tr><td><code>运行</code>:<code>jobs</code>:<code>result_status</code></td><td>作业的执行状态： <code>pending</code>, <code>done</code> 或 <code>faulted</code>.</td><td>字符串</td></tr><tr><td><code>运行</code>:<code>jobs</code>:<code>created_at</code></td><td>作业创建时间戳</td><td>字符串</td></tr><tr><td><code>运行</code>:<code>jobs</code>:<code>result_created_at</code></td><td>作业完成并生成结果的时间戳</td><td>字符串</td></tr></tbody></table>

### 获取计划作业

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}/jobs`
* **方法**: `GET`
* **认证**: `Basic`

#### 输出

下面的负载包含一个示例响应：截至目前该计划创建的所有作业 ID。

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

### 获取计划信息

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}`
* **方法**: `GET`
* **认证**: `Basic`

#### 输出

下面的负载包含一个示例计划信息响应。在首次运行之前， `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>浮点数</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>done</code> （作业已成功完成）、 <code>faulted</code> （作业失败）。</td><td>字符串</td></tr><tr><td><code>job_count</code></td><td>导致该特定 <code>状态</code>.</td><td>整数</td></tr><tr><td><code>stats : job_result_outcomes : ratio</code></td><td>具有该特定状态的作业数量与已创建作业总数之间的比率。</td><td>浮点数</td></tr></tbody></table>

### 停用或重新启用计划

#### 概览

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

* **端点**: `https://data.oxylabs.io/v1/schedules/{id}/state`
* **方法**: `PUT`
* **认证**: `Basic`

#### 输入

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

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

如果你将 `active` 设置为 `true`，你可以重新启用之前已停止的计划。

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

**输出**

```json
null
```

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

## API 响应码

关于 API 响应码，请参阅 [**API**](/products/cn/web-scraper-api/response-codes.md#api) 部分。缺少或无效参数的计划请求将被拒绝，返回 HTTP `422` 以及一个 `详细` 列表，列出该字段名称；未知的计划 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.