1.综述

通过我们提供的接口,你可以轻松获取八爪鱼任务信息和采集到的数据,还可操作任务的启停(增值接口 ),再配合您的程序可实现高效的数据采集与归档。在此之前, 您应该拥有一个八爪鱼数据平台的账号,并且建立了能够正常采集数据的任务。(还没有八爪鱼账号?点此注册

为满足不同类型用户的需求,我们设计了两套接口,一套为基本DataAPI接口,提供了获取任务信息和数据的功能。 另外一套除了包含基本DataAPI所有接口,还提供了获取任务状态和控制任务启停的增值接口(另售),详细区别请参考二者文档。

1.1.文档版本

当前版本: V2.0

历史版本: V1.0

1.2.联系方式

联系人:八爪鱼技术支持

邮箱:support@skieer.com

1.3.URI 规范

我们提供的接口都应该基于如下URL访问:

BaseURL: https://advancedapi.bazhuayu.com/

例如:【根据偏移量获取任务数据】的完整访问地址应该是GET https://advancedapi.bazhuayu.com/api/alldata/GetDataOfTaskByOffset?taskId={taskId}&offset={offset}&size={size}

注意:对于本文档出现的 {xxxx} ,它表示占位符,你需要用实际真实的值来替换它。 比如:对于用户名的占位符{username},在需要使用username={username}时,如果你的用户名是bazhuayu,则需要替换{username}为bazhuayu,即你需要构造出username=bazhuayu后方可正常使用它。

1.4.获取OAuth2.0 Token

在使用八爪鱼其他接口之前,你需要获得我们提供的基于OAuth2.0 的【Access Token】作为访问通行证。

1.4.1.获取全新Token

你需要提供一次八爪鱼平台的用户名和密码来获取全新【Access Token】。

请求

POST https://advancedapi.bazhuayu.com/token

请求包含信息

username={userName}&password={password}&grant_type=password

信息格式

application/x-www-form-urlencoded

响应

【Access Token】实体

信息格式

application/json, text/json

示例数据
{
    "access_token": "ABCD1234", 	     //访问通行证
    "token_type": "bearer",		             //token类型
    "expires_in": 86399,		                 //access_token有效时间(秒)(推荐在有效期间内推荐重复使用) 
    "refresh_token": "refresh_token"	 //刷新access_token的凭证
}

其中的【access_token】是以下所有接口访问的许可标志,请在访问每一个接口时都将【access_token】按照如下固定格式加入到的HTTP请求头中:

HeaderName: Authorization
Value: bearer {access_token}

注意:使用【access_token】构造的键值对时,请留意在 "bearer"与【access_token】字符串之间有个空格,结果类似于 "Authorization: bearer AA11BB22...CC33"。 获取的【access_token】具有有效期,我们推荐在有效期内重复使用。

1.4.2.刷新Token

上一次请求的【Access Token】实体中的【access_token】过期后,可以使用同一实体中的【refresh_token】刷新【Access Token】,方法与获取全新Token类似,修改【请求包含信息】即可。

注意:同一个【refresh_token】只能使用一次,使用后即失效。

请求

POST https://advancedapi.bazhuayu.com/token

请求包含信息

refresh_token={refresh_token}&grant_type=refresh_token

信息格式

application/x-www-form-urlencoded

响应

获取全新Token

提示:获取Token时正常情况返回的状态码为200,若返回非200请移步通用状态码参考来尝试解决问题。

2.接口说明

访问频率限制

为了更稳定地使用我们的服务,建议接口访问频率不超过20次/秒,访问过快有可能会收到429的状态码而导致访问失败,此时请降低访问频率到20次/秒以下或者更低。

我们建议以平稳的频率访问接口(例如1次/秒),不要在短时间内集中高频访问(例如在前1秒内访问了20次)。

提示:实际上我们采用了【漏桶算法】来限制访问:初始限制为20次每秒,桶大小为5秒,如果你n(n<=5)秒内没有访问接口,则频率限制宽限为n*20次每秒,即5秒内的最大访问量为100次,你可以在某个5秒内的任一秒内访问100次,但是其他4秒内则均不可访问,直到下个5秒开始。

特殊状态

以下接口正常情况下返回的状态码为200,若返回非200状态码请移步通用状态码参考来尝试解决问题。

2.1. 获取任务组信息

2.1.1.得到该用户所有的任务组

请求

响应

用户任务组Json元素的数组格式和状态信息

信息格式

application/json, text/json

示例数据
{
  "data": [
    {
      "taskGroupId": 1,
      "taskGroupName": "示例组1"
    },
    {
      "taskGroupId": 2,
      "taskGroupName": "示例组2"
    }
  ],
  "error": "success",
  "error_Description": "操作成功"
}

2.2. 任务操作

2.2.1.获取任务组中的任务

请求

请求包含信息
参数名称描述备注
taskGroupId

任务组Id

请在 请求URL(reuquest url)中定义此参数。

响应

返回任务Id(taskId),任务名(taskName)和任务创建者(creationUserId)组成的Json元素的数组和状态信息

信息格式

application/json, text/json

示例数据
{
  "data": [
    {
      "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
      "taskName": "示例任务1",
      "creationUserId": "5d1e4b3c-645c-44ab-ac0e-bfa9ad600ece"
    },
    {
      "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
      "taskName": "示例任务2",
      "creationUserId": "5d1e4b3c-645c-44ab-ac0e-bfa9ad600ece"
    }
  ],
  "error": "success",
  "error_Description": "操作成功"
}

2.2.2.批量获取任务状态

此接口可获取多个任务的运行状态。

请求

请求包含信息
参数名称描述备注
taskIdList

Json数组格式的taskId列表

请在 请求主体(request body)中定义此参数。

信息格式

application/json, text/json

示例数据
{
  "taskIdList": [
    "337fd7d7-aded-4081-9104-2b551161ccc8",
    "4adf489b-f883-43fa-b958-0cfde945ddb7"
  ]
}

响应

任务状态信息(其中status定义为:运行中 = 0,已停止 = 1,已完成 = 2,待运行 = 3,未执行 = 5 )

信息格式

application/json, text/json

示例数据
{
  "data": [
    {
      "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
      "taskName": "示例任务1",
      "status": 1
    },
    {
      "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
      "taskName": "示例任务2",
      "status": 2
    }
  ],
  "error": "success",
  "error_Description": "操作成功"
}

2.2.3.获取任务规则流程步骤的参数值

此接口可以获取任务规则某流程步骤的参数值,目前支持【打开网页】的Url(navigateAction1.Url)、【输入文本】的文本值(enterTextAction1.Text)、【循环】的文本列表(loopAction1.TextList)和Url列表(loopAction2.UrlList)的参数值获取。

请求

请求包含信息
参数名称描述备注
taskId

任务ID

请在 请求URL(reuquest url)中定义此参数。

name

属性名(支持navigateAction1.Url, enterTextAction1.Text, loopAction1.UrlList/TextList)

请在 请求URL(reuquest url)中定义此参数。

响应

步骤的参数值集合和状态信息

信息格式

application/json, text/json

示例数据
{
  "data": [
    "http://www.bazhuayu.com/",
    "http://www.skieer.com/"
  ],
  "error": "success",
  "error_Description": "操作成功"
}

2.2.4.更新任务规则流程参数值

此接口可更新任务规则流程步骤的参数值,目前支持更新【打开网页】的Url(navigateAction1.Url)、【输入文本】的文本值(enterTextAction1.Text)、【循环】的文本列表(loopAction1.TextList)和Url列表(loopAction2.UrlList)。

注意:对于Url和文本值请直接使用字符串类型:"value":"navigateAction1.Url",对具有N个项的文本列表或Url列表的值(value),请使用以逗号分隔的数组类型:"value":["text1","text2","text3",...,"textN"]。

请求

请求包含信息
参数名称描述备注
ruleParaInfo

任务流程的参数信息(支持navigateAction1.Url, enterTextAction1.Text, loopAction1.UrlList/TextList)

请在 请求主体(request body)中定义此参数。

信息格式

application/json, text/json

示例数据
{
  "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
  "name": "loopAction2.TextList",
  "value": "['八爪鱼','视界信息']"
}

响应

更新成功与否

信息格式

application/json, text/json

示例数据
{
  "error": "success",
  "error_Description": "操作成功"
}

2.2.5.在任务规则循环列表中添加新项

此接口可在任务规则循环列表中添加新项,目前支持添加【循环】的文本列表和Url列表。

注意:对文本列表和Url列表的参数值(value),请使用格式["text1","text2","text3",...,"textN"]来表示列表的N个项。

请求

请求包含信息
参数名称描述备注
ruleParaInfo

任务规则的某循环的参数信息

请在 请求主体(request body)中定义此参数。

信息格式

application/json, text/json

示例数据
{
  "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
  "name": "loopAction1.UrlList",
  "value": "['http://www.bazhuayu.com/', 'http://www.skieer.com/']"
}

响应

添加成功与否

信息格式

application/json, text/json

示例数据
{
  "error": "success",
  "error_Description": "操作成功"
}

2.2.6.启动任务

请求

请求包含信息
参数名称描述备注
taskId

任务ID

请在 请求URL(reuquest url)中定义此参数。

响应

启动状态(1:成功,2:任务正在执行中,5:任务规则配置不正确,6:无权使用,100:其他错误)

信息格式

application/json, text/json

示例数据
{
  "data": 1,
  "error": "success",
  "error_Description": "操作成功"
}

2.2.7.停止任务

请求

请求包含信息
参数名称描述备注
taskId

任务ID

请在 请求URL(reuquest url)中定义此参数。

响应

停止成功与否

信息格式

application/json, text/json

示例数据
{
  "error": "success",
  "error_Description": "操作成功"
}

2.2.8.清空任务数据

请求

请求包含信息
参数名称描述备注
taskId

任务ID

请在 请求URL(reuquest url)中定义此参数。

响应

清空任务数据成功与否

信息格式

application/json, text/json

示例数据
{
  "error": "success",
  "error_Description": "操作成功"
}

2.3. 导出任务数据

2.3.1.导出一批任务数据

此接口可导出任务未导出过的数据,导出成功后将数据标记为【正在导出】(而非【已导出】)状态,故可多次调用此接口导出同一批数据,在你确认数据被正确接收后再调用【标记数据为已导出状态】接口即可。

注意:若在导出数据时发生了意外(比如网络中断),请再次调用此接口重新导出未成功传输的这批数据(不记录断点)。

请求

请求包含信息
参数名称描述备注
taskId

任务Id

请在 请求URL(reuquest url)中定义此参数。

size

数据条数(范围:[1,1000])

请在 请求URL(reuquest url)中定义此参数。

响应

任务数据和状态信息

信息格式

application/json, text/json

示例数据
{
  "data": {
    "total": 100000,
    "currentTotal": 4,
    "dataList": [
      {
        "词条": "深圳视界",
        "简介": "领先的信息化解决方案提供商,致力于企业级数据整合,网页数据采集,整理,分析和挖掘。"
      },
      {
        "词条": "八爪鱼",
        "简介": "它彻底改变了大家对爬虫和采集器的认知,让网页数据采集变得前所未有的简单。"
      },
      {
        "词条": "数多多",
        "简介": "致力于打造大数据共享与交易平台。"
      },
      {
        "词条": "微图",
        "简介": "一款简单易用的数据分析及可视化工具,支持自然语言分析及文本挖掘。"
      }
    ]
  },
  "error": "success",
  "error_Description": "操作成功"
}

2.3.2.标记数据为已导出状态

当调用【导出一批任务数据】导出某任务一批数据后,这批数据状态从【未导出】变为【正在导出】,调用此接口会将该任务当前所有【正在导出】状态的数据更新为【已导出】状态。

注意:请确认通过【导出一批任务数据】(api/notexportdata/gettop)接口返回的结果被正确完整接收后再调用此接口。

请求

请求包含信息
参数名称描述备注
taskId

任务Id

请在 请求URL(reuquest url)中定义此参数。

响应

是否更新成功

信息格式

application/json, text/json

示例数据
{
  "error": "success",
  "error_Description": "操作成功"
}

2.4. 获取任务数据

2.4.1.根据起始偏移量获取任务数据

此接口根据数据起始偏移量(offset)和请求数据量获取任务数据,初始请求请将偏移量设置为0(offset = 0),数据量size ∈[1,1000],每次通过此接口请求数据返回的偏移量(offset > 0)可以作为读取下一批数据的起始偏移量。例如某任务有1000条数据, 第一次调用offset = 0, size = 100,则将会返回任务的头100条数据,以及下一次的起始偏移量offset = x(x不一定等于100)。第二次调用时请求参数设置为offset = x,size = 100,则返回任务的第101-200条数据,以及下一次起始偏移量offset=x1,然后用x1作为下次的起始偏移量,以此类推。

注意:此接口只用来读取数据,不会影响数据的导出状态,有关导出状态的详细介绍请参考【标记数据为已导出状态】。

请求

请求包含信息
参数名称描述备注
taskId

任务Id

请在 请求URL(reuquest url)中定义此参数。

offset

数据偏移量,当offset小等于0时,则从起始位置读取任务数据

请在 请求URL(reuquest url)中定义此参数。

size

要获取的数据量(范围:[1,1000])

请在 请求URL(reuquest url)中定义此参数。

响应

任务数据和状态信息

信息格式

application/json, text/json

示例数据
{
  "data": {
    "offset": 4,
    "total": 100000,
    "restTotal": 99996,
    "dataList": [
      {
        "词条": "深圳视界",
        "简介": "领先的信息化解决方案提供商,致力于企业级数据整合,网页数据采集,整理,分析和挖掘。"
      },
      {
        "词条": "八爪鱼",
        "简介": "它彻底改变了我对爬虫和采集器的认识,让网页数据采集变得前所未有的简单。"
      },
      {
        "词条": "数多多",
        "简介": "致力于打造大数据共享与交易平台。"
      },
      {
        "词条": "微图",
        "简介": "一款简单易用的数据分析及可视化工具,支持自然语言分析及文本挖掘。"
      }
    ]
  },
  "error": "success",
  "error_Description": "操作成功"
}

3.其他参考

3.1.通用状态码参考

若接口返回了意外结果请参考如下状态码来尝试解决问题。

HTTP Code 简码 描述

200

ok

JSON数据/状态信息/无内容。

400

invalid_grant

账号名或密码不正确。

400

unsupported_grant_type

POST数据格式不正确,要保证格式为:username={username}&password={password}&grant_type=password。

401

unauthorized

access_token无效 ,原因是token过期或者非法,此时需要重新获取token。

403

user_not_allowed

用户权限不足,DataAPI请升级到旗舰版,增值API请联系商务:0755-26646350。

404

not_found

找不到与请求 URI“xxxxxxxxxxx”匹配的 HTTP 资源,请使用正确的URL发起请求。

405

method_not_allowed

请求的资源不支持 http 方法“XXXX”,请使用该接口支持的方法请求。

429

quota_exceeded

API访问频率过快,限制频率为20次/秒,请降低访问频率。

503

service_unavailable

服务暂时不可用,请稍后重试。

3.2.示例代码参考

示例代码:

C# 版:ApiSamples/Code/CSharp/

Python 版:ApiSamples/Code/Python/

(其他语言版本即将推出)

3.3.使用协议

使用协议: 八爪鱼服务条款