OnPage API 强制停止任务

POST /v3/on_page/force_stop

本接口用于强制停止指定网站的抓取任务。请求中提供的任务 ID 所对应的任务将停止执行。任务停止前已完成扫描的页面数据仍可在任务结果中获取。

请求方法与路径：

POST https://api.seermartech.cn/v3/on_page/force_stop

计费说明

调用本接口不收取费用。任务停止后，您仍可在 30 天获取停止前已生成的结果。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

请求体使用 UTF-8 编码的 JSON 格式，并且是 JSON 数组。每个数组代表一个需要强制停止的任务。

单次请求最多可提交 1000 个任务 ID。

请求参数

字段	类型	填	说明
id	string	是	任务 ID。该 ID 可从创建任务接口 POST /v3/on_page/task_post 的响应中获取。格式为 UUID，例如：07131248-1535-0216-1000-17384017ad04

请求示例

[
  {
    "id": "08121600-1535-0216-0000-37b4c7a34453"
  },
  {
    "id": "08121600-1535-0216-0000-d6a5000b6897"
  }
]

响应说明

接口返回 JSON 对象 tasks 数组每个任务的处理结果。

顶层响应字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整状态码请参考错误码说明。
status_message	string	通用状态信息。
time	string	接口执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	tasks 数组中返回错误的任务数量。
tasks	array	任务处理结果数组。

tasks 数组字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式。
status_code	integer	当前任务的状态码，通常在 10000 至 60000 范围。
status_message	string	当前任务的状态信息。
time	string	当前任务的执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量。
path	array	请求路径信息。
data	object	创建任务时提交的参数。
result	array | null	任务结果数组。强制停止接口通常返回 null。

建议客户端根据 status_code 和 status_message 处理异常及任务级错误。

错误码

接口可能返回以下层级的状态码：

• HTTP 状态码：表示请求是否成功到达服务端。
• 顶层 status_code：表示本次 API 请求的整体处理结果。
• tasks[].status_code：表示单个任务的处理结果。

请在客户端实现错误重试、无效任务 ID 处理和任务状态校验逻辑。

curl 示例

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/force_stop" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "id": "08121600-1535-0216-0000-37b4c7a34453"
    }
  ]'

Python 示例

import requests

url = "https://api.seermartech.cn/v3/on_page/force_stop"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# 请求体是 JSON 数组
post_data = [
    {
        "id": "08121600-1535-0216-0000-37b4c7a34453"
    }
]

response = requests.post(url, headers=headers, json=post_data)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript 示例

import axios from "axios";

const postData = [
  {
    id: "08121600-1535-0216-0000-37b4c7a34453",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/force_stop",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络或接口请求异常：", error.message);
  });

响应示例

{
  "version": "0.1.20210805",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1008 sec.",
  "cost": 0,
  "tasks_count": 2,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "08121600-1535-0216-0000-37b4c7a34453",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0215 sec.",
      "cost": 0,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "on_page",
        "function": "force_stop",
        "target": "example.com",
        "max_crawl_pages": 10,
        "enable_javascript": true,
        "load_resources": true,
        "allow_subdomains": true
      },
      "result": null
    },
    {
      "id": "08121600-1535-0216-0000-d6a5000b6897",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0227 sec.",
      "cost": 0,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "on_page",
        "function": "force_stop",
        "target": "example.org",
        "max_crawl_pages": 10,
        "enable_javascript": true,
        "load_resources": true,
        "allow_subdomains": true
      },
      "result": null
    }
  ]
}

实用场景

• 终止异常膨胀的站点抓取任务：当页面数量或抓取范围出预期时及时停止任务，持续占用抓取资源。
• 停止误的爬虫任务：发现目标域名、子域名权限或 JavaScript 渲染错误时立即中止，减少无效数据产生。
• 控制批量 SEO 审计进程：在批量审计任务达到所需页面数量后停止抓取，加快后续分析流程。
• 取消临时测试任务：测试抓取规则或站点时，在确认结果足够后主动停止任务，保持任务队列整洁。
• 管理高峰期抓取资源：在系统负载较高或需要优执行项目时暂停指定任务，优化整体抓取资源分。