Web Scraper API – 创建任务

选择一个采集模板，提交目标网址等参数，即可创建 Web Scraper 任务。你可以等待结果返回，也可以先获取任务 ID，稍后查询结果。

POST /v1/web-scraper/task/create

快速开始 #

调用前，请准备 API Key，并从产品的模板页面获取模板代码和输入参数说明。确保当前套餐支持该模板，且账户余额充足。

下面以 Amazon 商品采集为例。请将 <API_KEY> 和示例商品网址替换为你的 API 地址、API Key 和目标网址。本文数据仅用于演示。

curl --request POST 'https://data.clawoxy.com/v1/web-scraper/task/create' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "template_code": "amazon_product_by_url",
    "mode": "async",
    "input": {
      "url": "https://www.amazon.com/dp/B0EXAMPLE1"
    }
  }'

任务创建后，返回 HTTP 202：

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "01a0576790007a81b21db0d8b61eaabc",
    "template_code": "amazon_product_by_url",
    "mode": "async",
    "status": "queued",
    "result_status": "not_ready",
    "error": null,
    "result": null,
    "result_url": null,
    "result_url_expires_at": null,
    "created_at": 1788172800,
    "completed_at": null,
    "result_expires_at": null
  }
}

保存 task_id，通过查询任务详情获取进度和结果。queued 表示任务正在排队，尚未完成。

请求参数 #

请求头 #

请求头	必填	说明
Authorization	是	填写 Bearer <API_KEY>
Content-Type	是	填写 application/json

请求体 #

使用 JSON 对象提交以下参数：

参数	类型	必填	说明
template_code	string	是	模板代码，例如 amazon_product_by_url
mode	string	是	async：同步采集 sync：异步采集
input	object	是	采集参数，按所选模板的说明填写，例如目标网址 url

不同模板的 input 字段可能不同。国家或地区等可选参数，也请以对应模板的说明为准；模板未支持的额外字段不会生效。

如何选择模式 #

模式	适合的用法	如何获取结果
async	希望先提交任务，稍后获取结果	返回 HTTP 202，保存任务 ID 后查询详情
sync	希望在同一次请求中等待结果	任务完成后返回 HTTP 200；如果仍在处理，则返回 HTTP 202，继续查询详情

使用同步模式，只需将请求中的 "mode": "async" 改为 "mode": "sync"，其他参数不变。

同步模式也可能需要后续查询。请求等待结束或连接断开，不会取消已经创建的任务，请保留任务 ID，避免重复提交。

成功响应 #

任务是否采集成功，请查看 data.status。code=0 表示本次请求成功，不代表采集已经完成。

同步采集完成时，可能直接返回结果，HTTP 200：

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "01a0576790007a81b21db0d8b61eaabc",
    "template_code": "amazon_product_by_url",
    "mode": "sync",
    "status": "succeeded",
    "result_status": "available",
    "error": null,
    "result": {
      "url": "https://www.amazon.com/dp/B0EXAMPLE1",
      "asin": "B0EXAMPLE1",
      "title": "示例商品"
    },
    "result_url": null,
    "result_url_expires_at": null,
    "created_at": 1788172800,
    "completed_at": 1788172812,
    "result_expires_at": 1788432012
  }
}

result 中的字段由模板决定，上面仅展示部分商品字段。当结果较大时，result 为 null，请使用 result_url 下载 JSON 结果。

响应字段 #

字段	类型	说明
code	integer	0 表示请求成功，其他值见错误码说明
message	string	请求成功时为 success，请求失败时为英文错误说明
data	object 或 null	任务信息；请求失败时为 null

data 包含以下字段：

字段	类型	说明
task_id	string	任务 ID，用于查询进度和结果
template_code	string	使用的模板代码
mode	string	创建时选择的 sync 或 async
status	string	任务状态，见下表
result_status	string	结果是否可获取，见下表
error	object 或 null	任务失败原因，包含 code 和 message；未失败时为 null
result	object、array 或 null	直接返回的采集结果；没有直接返回结果时为 null
result_url	string 或 null	JSON 结果下载链接；与 result 不会同时有值
result_url_expires_at	integer 或 null	下载链接到期时间；没有链接时为 null
created_at	integer	任务创建时间
completed_at	integer 或 null	任务完成时间；尚未完成时为 null
result_expires_at	integer 或 null	结果保留截止时间；尚未成功或任务失败时为 null

时间字段均为秒级 Unix 时间戳。

根据状态继续操作 #

status	result_status	含义	下一步
queued	not_ready	排队中	稍后查询详情
running	not_ready	采集中	稍后查询详情
succeeded	available	采集成功	读取 result 或下载 result_url
succeeded	expired	结果已过期	无法再获取该任务的结果
failed	unavailable	采集失败	查看 error 中的原因

获取采集结果 #

如果返回了 result，可直接读取其中的数据。如果返回了 result_url，使用完整链接下载：

curl '<RESULT_URL>' --output result.json

将 <RESULT_URL> 替换为响应中的链接。下载时不需要附加 API Key，请妥善保管链接，不要公开分享。

任务尚未完成时，建议每隔 2～5 秒查询一次详情，完成或失败后停止查询。

请在 result_expires_at 前保存结果。下载链接过期后，只要结果仍在保留期内，就可以查询详情获取新链接；结果保留期结束后则无法重新获取。

错误处理 #

请求未成功 #

当 code 不为 0 时，请根据错误码处理。例如，余额不足会返回 HTTP 402：

{
  "code": 120301,
  "message": "balance is insufficient",
  "data": null
}

错误码	HTTP	原因	建议操作
100301	400	请求参数不正确	检查 JSON 格式、必填项和模板参数要求
120102	401	API Key 缺失或无效	检查 API Key 和 Authorization 请求头
120103	403	API Key 已停用	确认 API Key 状态
120104	500	API Key 状态异常	联系客服协助处理
120205	500	套餐状态异常	联系客服协助处理
120301	402	余额不足	补充余额后重试
120402	429	当前任务过多	等待已有任务完成后再提交
120405	503	服务暂时不可用	先核对是否已创建任务，再决定是否重试
120406	400	不支持所选国家或地区	查看模板支持的国家或地区
120501	404	模板不存在或不可用	检查模板代码和可用状态
120502	403	当前套餐不支持该模板	确认套餐支持的模板
120503	404	无法获取任务信息	联系客服核对任务，避免重复提交
120507	429	提交过于频繁	降低请求频率，稍后再试

任务采集失败 #

如果请求成功，但 data.status 为 failed，请查看 data.error。例如，该字段可能返回：

{
  "code": 120403,
  "message": "任务在数据采集过程中失败。"
}

data.error.code	含义	建议操作
120403	采集失败或未获得有效结果	检查目标网址和模板参数后，再决定是否重新采集
120404	采集超时	稍后按需重新采集

同步请求返回失败任务时，HTTP 状态仍为 200，请通过 status 和 error 判断采集结果。