# 任务管家

[**任务管家**](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. 告知我们 **何时停止** 方法是提交结束时间。

&#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`
* **身份验证**: `基础`
* **请求头**: `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>项</code></strong></mark></td><td>应作为计划一部分执行的网页爬虫API 任务参数集列表。</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" %}
**注意**：有关如何为 **`项`** 任务管家 载荷中的该部分组装任务参数集的指导，请参阅您希望使用的特定爬虫的文档页面（例如 [**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`
* **身份验证**: `基础`

#### 输出

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

请参阅下面的示例响应。

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

### 获取运行信息

#### 概览

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

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

#### 输出

下面的载荷包含一个示例 `/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`
* **身份验证**: `基础`

#### 输出

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

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

### 获取计划信息

#### 概览

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

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

#### 输出

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

<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": "完成",
                "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`
* **身份验证**: `基础`

#### 输入

使用此端点停止或重新启动计划。&#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: 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.