> 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).

# 任务管家

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

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

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

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

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

## 快速开始

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

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

&#x20;参见 [**此处**](#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/wang-ye-pa-chong-api-ji-cheng/postman.md).
{% endhint %}

## 端点

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

* [**创建新计划**](#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`
* **Authentication**: `基础`
* **请求头**: `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="color:默认;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="color:默认;background-color:green;"><strong><code>items</code></strong></mark></td><td>应作为计划一部分执行的 Scraper APIs 任务参数集列表。</td><td>-</td></tr><tr><td><mark style="color:默认;background-color:green;"><strong><code>end_time</code></strong></mark></td><td>计划应停止运行的时间。注意：结束时间包含在内。</td><td>-</td></tr></tbody></table>

&#x20;    \- 必填参数

{% hint style="info" %}
**注意**：关于为 **`items`** 任务管家负载中的这部分组装任务参数集的指导，请参考你想使用的特定爬虫的文档页面（例如 [**Google**](/api-targets/cn/sou-suo-yin-qing/google.md), [**Amazon**](/api-targets/cn/dian-zi-shang-wu/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"
}
```

#### 输出

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

```json
{
    "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 列表。

请参见下面的示例响应。

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

### 获取运行信息

#### 概述

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

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

#### 输出

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

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

<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>任务的执行状态（例如，"done"、"failed"、"pending"）。</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>

### 获取计划任务

#### 概述

使用此端点获取作为执行计划结果而运行的抓取任务列表。&#x20;

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

#### 输出

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

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

### 获取计划信息

#### 概述

使用此端点获取特定计划的信息。&#x20;

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

#### 输出

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

<pre class="language-json"><code class="lang-json">{
    "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",
<strong>    "links": [
</strong>        {
            "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
            }
        ]
    }
}
</code></pre>

<table><thead><tr><th width="216">键</th><th>说明</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>链接</code></td><td>一组链接对象，定义与计划资源相关的可用 API 端点。</td><td>数组</td></tr><tr><td><code>链接</code>:<code>rel</code></td><td>解释链接相对于父资源用途的关系标识符。</td><td>字符串</td></tr><tr><td><code>链接</code>:<code>href</code></td><td>API 端点的 URL 路径。表示可访问的资源位置。</td><td>字符串</td></tr><tr><td><code>链接</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>job_result_outcomes</code></td><td>包含作为计划一部分执行的抓取/解析任务结果统计。</td><td>JSON 数组</td></tr><tr><td><code>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>status</code>.</td><td>整数</td></tr><tr><td><code>ratio</code></td><td>该特定状态的任务数量与已创建任务总数之间的比率。</td><td>浮点数</td></tr></tbody></table>

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

#### 概述

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

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

#### 输入

使用此端点停止或重新启动计划。&#x20;

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

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

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

**输出**

```json
null
```

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

## API 响应码

有关 API 响应码，请参见 [**API**](/products/cn/web-scraper-api/response-codes.md#api) 部分。


---

# 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:

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

The question should be specific, self-contained, and written in natural language.
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.