云采集 API

支持启动、停止任务，拉取采集数据等云采集相关的操作。

云采集相对本地采集而言，具有全程托管、无须购买机器，高性能快速采集，易于和企业/个人工作流集成等优势。

术语介绍

术语	说明
任务	用于配置采集步骤和规则的集合。不同的采集目标网站通常配置到不同的任务，例如采集亚马逊商品类目数据可以配置到一个任务里，而采集亚马逊商品列表和详情可以配置到另一个任务里。相关接口及字段名关键词是 task。
批次	记录任务的运行历史，每次运行任务都会产生一个新的批次。相关接口及字段名关键词是 batch。
子任务	运行任务时，可以将任务拆分为多个子任务来并发运行，以提高采集效率、缩短采集时间。当前支持拆分子任务的`步骤`是循环，并且`循环方式`是`循环列表`、并且`列表类型`是`网址列表`或`文本列表`。另外，为了降低任务配置的复杂度，仅支持流程最外层的`步骤`，嵌套在流程内层的`循环`不支持拆分。相关接口及字段名关键词是 job。
步骤	任务流程配置中的一个逻辑单元，例如打开网页、刷新、点击元素等。相关接口及字段名关键词是 action。
代理	在云服务器中运行采集任务的代理程序。相关接口及字段名关键词是 agent。

POST Start Task

启动云采集任务。每次运行都会产生一个新的批次（batch）。

POST /cloud/start

Body 请求参数

json

{
  "taskID": "9b57f4b8-c5d5-44ac-b4be-52ea63ae4742",
  "region": "us",
  "nodeCount": 1,
  "jobCount": 4,
  "actionParams": "[{\"id\": \"0d2904db-b128-4862-ad46-708244b2c753\",\"value\": \"https://www.coolparse.com\"},{\"id\": \"87f25dc4-5d5f-47dc-a378-f5bc9f3a7fbc\",\"value\": \"some text\"},{\"id\": \"a7ce70e2-5932-4b07-a910-b0bba80ea2c6\",\"value\": 22},{\"id\": \"fb4ead12-99bc-438b-9c81-29bb547c9a33\",\"value\": [\"https://www.coolparse.com/loop1\",\"https://www.coolparse.com/loop2\",\"https://www.coolparse.com/loop3\",\"https://www.coolparse.com/loop4\"]}]"
}

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	none
x-cp-request-id	header	string	是	none
body	body	object	否	none
» taskID	body	string	是	任务 ID，从任务概览中复制。
» region	body	string	否	云采集 agent 运行的区域。
» nodeCount	body	integer	是	云采集 agent 最大运行个数。
» jobCount	body	integer	是	将任务拆分为多少个 job 来执行，结合 nodeCount 可高并发运行任务、大幅提高采集效率。
» actionParams	body	string	否	替换 action 的字段值参数列表。

详细说明

» region: 云采集 agent 运行的区域。

留空表示使用默认区域（随机分配空闲的 agent）。可用区域如下：

us United States
gb Great Britain
hk Hong Kong (China)
jp Japan

» actionParams: 替换 action 的字段值参数列表。

支持替换的步骤及默认字段说明

步骤	字段名	字段 JSON path	值类型	描述
打开网页	网址	config.url	string	可用于每次运行时传入不同 URL 参数等场景。
输入文本	输入内容	config.text	string	可用于每次运行时输入不同搜索关键词或文本等场景。
循环	循环次数	config.times	int	`循环方式`是`按次数循环`时可用。
循环	网址列表	config.urls	string 数组	`循环方式`是`循环列表`、且`列表类型`是`网址列表`、且`网址来源`是`手动输入`时可用。
循环	文本列表	config.texts	string 数组	`循环方式`是`循环列表`、且`列表类型`是`文本列表`时可用。
循环	自定义	config.times	int	`循环方式`是`循环翻页`、且`翻页次数`是`自定义`时可用。
循环	自定义	config.times	int	`循环方式`是`滚动翻页`、且`滚动次数`是`自定义`时可用。

参数对象数据结构

传参前先将 JSON 数组转为 string。

字段	描述
id	action 的 ID，从`点击复制步骤ID`按钮复制，入口在`任务编辑器`->actoin `编辑`。
path	当前对象的 JSON path。留空表示取该`步骤`的默认字段的 JSON path。
value	新的字段值。

示例：

json

[
    {
        "id": "0d2904db-b128-4862-ad46-708244b2c753",
        "value": "https://www.coolparse.com"
    },
    {
        "id": "87f25dc4-5d5f-47dc-a378-f5bc9f3a7fbc",
        "value": "some text"
    },
    {
        "id": "a7ce70e2-5932-4b07-a910-b0bba80ea2c6",
        "value": 22
    },
    {
        "id": "fb4ead12-99bc-438b-9c81-29bb547c9a33",
        "value": [
            "https://www.coolparse.com/loop1",
            "https://www.coolparse.com/loop2",
            "https://www.coolparse.com/loop3",
            "https://www.coolparse.com/loop4"
        ]
    }
]

转为 string 后（加转义）：

[{\"id\": \"0d2904db-b128-4862-ad46-708244b2c753\",\"value\": \"https://www.coolparse.com\"},{\"id\": \"87f25dc4-5d5f-47dc-a378-f5bc9f3a7fbc\",\"value\": \"some text\"},{\"id\": \"a7ce70e2-5932-4b07-a910-b0bba80ea2c6\",\"value\": 22},{\"id\": \"fb4ead12-99bc-438b-9c81-29bb547c9a33\",\"value\": [\"https://www.coolparse.com/loop1\",\"https://www.coolparse.com/loop2\",\"https://www.coolparse.com/loop3\",\"https://www.coolparse.com/loop4\"]}]

返回示例

json

{
  "code": 0,
  "data": {
    "batchID": 56693373452336,
    "taskID": "9b57f4b8-c5d5-44ac-b4be-52ea63ae4742",
    "createTime": 1731751954753,
    "updateTime": 1731751954753,
    "startTime": 0,
    "endTime": 0,
    "useTime": 0,
    "lineCount": 0,
    "duplicatedCount": 0,
    "captchaCount": 0,
    "ipProxyUsage": 0,
    "region": "us",
    "nodeCount": 1,
    "jobCount": 3,
    "status": 1,
    "fields": [
      {
        "id": "9a117f51-1451-4b4b-9d0f-1ec2e33c63ff",
        "name": "Title"
      },
      {
        "id": "1a1978dc-c9ce-4ec7-b64b-19b28a451e97",
        "name": "Link"
      },
      {
        "id": "a47a81b0-50df-4a33-ba78-efcbf34b7c0c",
        "name": "Description"
      }
    ]
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» code	integer	true	none	none
» data	object	true	none	开始运行的批次（batch）信息
»» batchID	integer	true	none	none
»» taskID	string	true	none	none
»» createTime	integer	true	none	none
»» updateTime	integer	true	none	none
»» startTime	integer	true	none	none
»» endTime	integer	true	none	none
»» useTime	integer	true	none	none
»» lineCount	integer	true	none	采集到的数据行数
»» duplicatedCount	integer	true	none	重复的数据行数
»» captchaCount	integer	true	none	验证码使用量
»» ipProxyUsage	integer	true	none	IP 代理使用量
»» region	string	true	none	none
»» nodeCount	integer	true	none	none
»» jobCount	integer	true	none	none
»» status	integer	true	none	none
»» fields	[object]	true	none	`数据提取`action 的字段配置
»»» id	string	true	none	none
»»» name	string	true	none	none

POST Stop Task

停止运行云任务。

POST /cloud/stop

Body 请求参数

json

{
  "taskID": "9b57f4b8-c5d5-44ac-b4be-52ea63ae4742"
}

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	none
x-cp-request-id	header	string	是	none
body	body	object	否	none
» taskID	body	string	是	none

返回示例

json

{
  "code": 0,
  "data": {
    "batchID": 56629190950176,
    "taskID": "9b57f4b8-c5d5-44ac-b4be-52ea63ae4742",
    "createTime": 1731250529000,
    "updateTime": 1731250529000,
    "startTime": 0,
    "endTime": 1731751949219,
    "useTime": 9223372036854,
    "lineCount": 0,
    "duplicatedCount": 0,
    "captchaCount": 0,
    "ipProxyUsage": 0,
    "region": "us",
    "nodeCount": 1,
    "jobCount": 3,
    "status": 4,
    "fields": [
      {
        "id": "9a117f51-1451-4b4b-9d0f-1ec2e33c63ff",
        "name": "Title"
      },
      {
        "id": "1a1978dc-c9ce-4ec7-b64b-19b28a451e97",
        "name": "Link"
      },
      {
        "id": "a47a81b0-50df-4a33-ba78-efcbf34b7c0c",
        "name": "Description"
      }
    ]
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» code	integer	true	none	none
» data	object	true	none	停止的 batch 信息
»» batchID	integer	true	none	none
»» taskID	string	true	none	none
»» createTime	integer	true	none	none
»» updateTime	integer	true	none	none
»» startTime	integer	true	none	none
»» endTime	integer	true	none	none
»» useTime	integer	true	none	none
»» lineCount	integer	true	none	none
»» duplicatedCount	integer	true	none	none
»» captchaCount	integer	true	none	none
»» ipProxyUsage	integer	true	none	none
»» region	string	true	none	none
»» nodeCount	integer	true	none	none
»» jobCount	integer	true	none	none
»» status	integer	true	none	none
»» fields	[object]	true	none	none
»»» id	string	true	none	none
»»» name	string	true	none	none

GET Get Batches

获取云采集任务的 batch 列表。

GET /cloud/batches

请求参数

名称	位置	类型	必选	说明
page	query	string	否	页码，从 1 开始。
size	query	string	否	一页最多返回的数据行数
taskID	query	string	否
orderBy	query	string	是	排序。0-按创建时间倒序, 1-按运行时间倒序, 2-按采集到的数据行数倒序。
Authorization	header	string	是	none
x-cp-request-id	header	string	是	none

返回示例

200 Response

json

{
  "code": 0,
  "data": {
    "list": [
      {
        "batchID": 0,
        "taskID": "string",
        "createTime": 0,
        "updateTime": 0,
        "startTime": 0,
        "endTime": 0,
        "useTime": 0,
        "lineCount": 0,
        "duplicatedCount": 0,
        "captchaCount": 0,
        "ipProxyUsage": 0,
        "region": "string",
        "nodeCount": 0,
        "jobCount": 0,
        "status": 0,
        "fields": [
          {
            "id": null,
            "name": null
          }
        ]
      }
    ],
    "pagination": {
      "page": 0,
      "size": 0,
      "total": 0
    }
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» code	integer	true	none	none
» data	object	true	none	none
»» list	[object]	true	none	batch 信息列表
»»» batchID	integer	false	none	none
»»» taskID	string	false	none	none
»»» createTime	integer	false	none	none
»»» updateTime	integer	false	none	none
»»» startTime	integer	false	none	none
»»» endTime	integer	false	none	none
»»» useTime	integer	false	none	none
»»» lineCount	integer	false	none	none
»»» duplicatedCount	integer	false	none	none
»»» captchaCount	integer	false	none	none
»»» ipProxyUsage	integer	false	none	none
»»» region	string	false	none	none
»»» nodeCount	integer	false	none	none
»»» jobCount	integer	false	none	none
»»» status	integer	false	none	none
»»» fields	[object]	false	none	none
»»»» id	string	true	none	none
»»»» name	string	true	none	none
»» pagination	object	true	none	none
»»» page	integer	true	none	none
»»» size	integer	true	none	none
»»» total	integer	true	none	none

GET Get Data

获取云任务采集的数据。batchID 可以从 Get Batches API 获取。

GET /cloud/data

请求参数

名称	位置	类型	必选	说明
page	query	string	否	none
size	query	string	否	none
orderBy	query	string	是	none
batchID	query	string	否	每次运行任务时，CoolParse 都会自动创建一个 batchID.
preview	query	boolean	否	"true" 表示预览数据，字段超过一定长度会截断。否则返回完整的数据。
deduplication	query	boolean	否	true" 表示去掉重复的数据行，包括本次请求的、以及之前相同 `deduplicationID` 的请求中的。相同行的定义是所有的字段值都相待。
deduplicationID	query	string	否	定义相同的请求序列，用于跨请求去重。从最近一次请求开始计算，1 小时后失效。
Authorization	header	string	是	none
x-cp-request-id	header	string	是	none

返回示例

json

{
  "code": 0,
  "data": {
    "list": [
      "{\"f19c720c-a430-49e0-b8ca-17f67da485bb\":\"data item 1\"}",
      "{\"f19c720c-a430-49e0-b8ca-17f67da485bb\":\"data item 2\"}",
      "{\"f19c720c-a430-49e0-b8ca-17f67da485bb\":\"data item 3\"}"
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 3
    }
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Inline

返回数据结构

状态码 200

名称	类型	必选	约束	说明
» code	integer	true	none	none
» data	object	true	none	none
»» list	[string]	true	none	none
»» pagination	object	true	none	none
»»» page	integer	true	none	none
»»» size	integer	true	none	none
»»» total	integer	true	none	none

云采集 API ​

POST Start Task ​

请求参数 ​

详细说明 ​

返回结果 ​

返回数据结构 ​

POST Stop Task ​

请求参数 ​

返回结果 ​

返回数据结构 ​

GET Get Batches ​

请求参数 ​

返回结果 ​

返回数据结构 ​

GET Get Data ​

请求参数 ​

返回结果 ​

返回数据结构 ​

云采集 API

POST Start Task

请求参数

详细说明

返回结果

返回数据结构

POST Stop Task

请求参数

返回结果

返回数据结构

GET Get Batches

请求参数

返回结果

返回数据结构

GET Get Data

请求参数

返回结果

返回数据结构