百度知道开放平台openAPI接口规范文档V10.docx
- 文档编号:19092746
- 上传时间:2023-04-24
- 格式:DOCX
- 页数:29
- 大小:585.48KB
百度知道开放平台openAPI接口规范文档V10.docx
《百度知道开放平台openAPI接口规范文档V10.docx》由会员分享,可在线阅读,更多相关《百度知道开放平台openAPI接口规范文档V10.docx(29页珍藏版)》请在冰豆网上搜索。
XX知道开放平台openAPI接口规范文档V10
XX知道开放平台OPENAPI接口规范文档V1.0
系统名称
XX知道开放平台OPENAPI服务接口
项目负责人
作者
陈霖
文档提交日期
2010-11-04
XX在线网络技术(北京)
(版权所有,翻版必究)
修改记录
No
修改后
版本号
修改内容简介
修改日期
修改人
1
XX知道OPENAPI服务接口
2010-11-04
陈霖
1背景
本文旨在为第三方合作站点应用访问知道频道开放服务提供统一的HTTP接口调用与交互规范。
本文中描述的规范包括知道频道的查询分类树信息、问题列表查询接口、检索查询接口、查询精彩推荐接口、查询用户信息接口、查询用户提问回答信息接口、查询用户排行榜接口、提问接口、回答接口、消息提醒接口、财富兑换接口和采纳最佳答案接口。
2规范适用对象说明
本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的OpenAPI。
3名词解释
●XX知道:
:
//zhidao
●各网站的XX知道频道:
●APIKEY:
注册API合作时由XX的OPENAPI平台分配的唯一标识一个应用的字符串,又称应用公钥
●APISECRET:
注册API合作时由XX的OPENAPI平台分配的应用密钥,用于平台与合作站点之间通信时的参数签名
4请求数据包格式规范
4.1URL
按照XXOpenAPI规范,XX知道频道OPENAPI提供如下REST风格的接口:
:
//zhidao.xxx/restserver/zhidao?
{query_string}
query_string由系统级参数部分和具体OpenAPI调用参数部分组成,以key1=value&key2=value2&…表示,对于采用POST请求的OpenAPI,query_string部分则是在POST请求体里。
所有查询类的OpenAPI接口既支持POST,也支持GET方式,提交类的OPENAPI接口仅支持POST方式。
4.2参数
4.2.1系统级参数
以下参数是由XXOpenAPI平台系统定义的,XX知道频道需要支持这些参数以便接入该平台提供开放接口。
XX知道频道采用应用授权认证接口方式,合作初始XX知道开放平台代第三方站点申请应用分配api_key和参数签名密钥api_secret。
表格41API系统级参数
参数名
类型
是否必需
描述
api_key
string
是
注册应用时分配到的apikey
method
string
是
采取baidu.zhidao.getQuestionList这样的命名空间方式制定方法名
call_id
uint
是
时间戳,系统时间的秒值,同个应用的不同api请求的time值应该是递增的,用于防replay攻击
format
string
否
响应包格式,可以是xml(默认)或json
ie
string
否
API调用请求包的编码类型,支持UTF-8和GBK
bd_sig
string
是
参数签名,对bd_sig外所有参数串的签名,包括业务级的参数。
4.2.2业务级参数的通用约定
XX知道频道遵守XXOpenAPI规范中业务级通用参数的约定。
表格42业务级参数的通用约定
参数名
类型
描述
page_no
Int
用于支持分页的api,默认为1,表示第几页
page_size
Int
用于支持分页的api,表示每页返回多少条数据,默认以及上限为25
4.2.3参数签名算法
参数签名生成算法采取如下方式(PHP版),其它语言根据注释描述完成等同功能:
//param_array是key-value形式的参数数组,不包括api_secret密钥本身
//secret是合作申请成功后分配的api_secret密钥
functiongenerate_sig($param_array,$secret){
$str='';
//对param_array中的参数名称进行升序排序
ksort($param_array);
//按照如下格式转换数组为string格式
foreach($param_arrayas$k=>$v){
$str.="$k=$v";
}
//string末端补充api_secret密钥
$str.=$secret;
//生成32位小写MD5为最终的数据签名
returnmd5($str);
}
注:
密钥是XX知道频道分配给第三方应用的secret_key,该算法返回的结果便是系统级参数中的bd_sig。
5响应数据包格式规范
响应数据包的格式由调用时传递的format参数指定(默认为xml格式),无论是xml格式还是json格式,输出内容都是UTF-8格式。
目前,XX知道频道目前支持xml、json格式。
5.1XML输出格式
●文档编码格式UTF-8
●接口的返回数据中,数组对应的xml节点包含list=”true”属性,其子节点的标签名跟对应的数据有联系,并且同个数组内的同级节点的标签名一致。
例如表示问题标题列表对应的xml输出可能为:
[CDATA[北京一共有几个区?
]]>
[CDATA[XX大厦的地址是什么?
]]>
●接口的返回数据中,对象类型和普通数据类型数据(string,int,double,bool)对应的xml节点不包含list属性或者list属性值为false,节点标签名具有实际意义,与数据所描述的信息相符。
例如,表示问题的数据对应的xml输出为:
[CDATA[XX大厦的地址是什么?
]]>
[CDATA[: //zhidao.xxx/question/b231e997ade585b3e99481e59bbd7a62310200]]
[CDATA[如题,XX大厦地址在]]
5.2json输出格式
API调用时如果传递format参数为json(大小写不敏感),则正常响应包符合如下规范的json字符串:
●响应头中的Content-Type指定为application/json,charset=utf-8
●字符串编码格式是UTF-8
字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串
5.3错误响应输出格式
错误响应输出内容符合以下规范:
●返回内容由error_code,error_msg,request_args这3个属性组成,分别用于描述错误码,错误信息,以及调用OpenAPI时所传递的所有参数的信息。
●request_args属性是一个数组,由n个包含key和value属性的对象组成
例如,假设第三方应用调用baidu.zhidao.getQuestionList接口时传递的参数api_key无效,则其对应的xml格式的错误响应包为如下格式:
xmlversion="1.0"encoding="UTF-8"?
>
[CDATA[cid]]>
[CDATA[249]]>
[CDATA[method]]>
[CDATA[baidu.zhidao.getQuestionLis]]>
Json格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串
6错误码定义
XX开放知道OPENAPI调用过程中可能会返回的错误码定义如下表所示:
error_code
error_msg
Description
0
Success
成功
1
Unknownerror
未知错误
2
Servicetemporarilyunavailable
后端服务暂时不可用
3
Unsupportedopenapimethod
Openapi接口不被支持
4
Openapirequestlimitreached
应用对openapi接口的调用请求数达到上限
5
UnauthorizedclientIPaddress:
%s
openapi调用端的IP未被授权
100
Invalidparameter
参数无效或缺失
101
InvalidAPIkey
Apikey无效
103
Invalidcall_idparameter
Call_id参数无效或已被使用过
104
Incorrectsignature
签名无效
105
Toomanyparameters
参数过多
106
Unsupportedsignaturemethod
参数签名算法未被平台所支持
200
Nopermissiontoaccessdata
没有权限访问数据
900
Nosuchapplicationexists
应用不存在
12001
Parametersformaterror
必选参数格式错误
12002
operateforinvalidquestion
问题生命已经结束
12003
Userwealthisnotenough
用户财富不足
12004
Nopermissiontosetbest
没有权限采纳此问题
7API接口细则
以下接口返回数据均是以XML格式为demo,JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。
7.1.getCatalogInfo
7.1.1功能
获取知道频道的分类树信息
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getCatalogInfo&call_id=1276418994&format=xml&bd_sig=sig-result
7.1.2参数
参数名
类型
描述
4.2.1系统级参数全体
7.1.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
cid
分类ID
cname
分类名称
topcid
分类的父级别分类id,如果topcid=0则分类为根级别分类
7.2baidu.zhidao.getQuestionList
7.2.1功能
基于知道频道分类ID获取对应分类下的问题列表
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getQuestionList&call_id=1276418994&format=xml&bd_sig=sig-result&cid=11&qstatus=0&page_no=2&page_size=25
7.2.2参数
参数名
类型
描述
4.2.1系统级参数全体
4.2.2业务级参数全体
cid
int
知道频道的分类ID
qstatus
int
问题状态0为待解决1为已解决
7.2.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
id
问题ID
url
该问题在知道频道的URL
title
问题标题
content
提问内容
cid
该问题在知道频道所属的分类ID
cname
该问题在知道频道所属的分类名称
7.3.getQuestionSearch
7.3.1功能
基于检索关键字在频道中搜索匹配的问题列表
URLDemo:
rver/zhidao?
api_key=1uMqYWpHo3MoLH&method.getQuestionSearch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=植物大站僵尸+游戏&qstatus=0&page_no=2&page_size=25
7.3.2参数
参数名
类型
描述
4.2.1系统级参数全体
4.2.2业务级参数全体
keywords
string
检索关键字多个检索关键字之间使用+号连接
qstatus
int
问题状态0为待解决1为已解决
7.3.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
id
问题ID
url
该问题在知道频道的URL
title
问题标题
content
提问内容
cid
该问题在知道频道所属的分类ID
cname
该问题在知道频道所属的分类名称
summary
已解决问题的最佳答案摘要,待解决问题无此字段
7.4.getQuestionInfo
7.4.1功能
基于频道问题ID获取对应问题的数据以及回答
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getQuestionInfo&call_id=127323494&format=xml&bd_sig=sig-result&qid=54a9e997ade585b3e99481e59bbd7a62310900
7.4.2参数
参数名
类型
描述
4.2.1系统级参数全体
qid
string
知道频道的问题ID
7.4.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
questionInfo
问题内容数据,具体明细参考
answerCount
问题包含回答数量
bestAnswers
最佳答案列表
answers
普通答案列表
content
回答内容
cite
回答参考资料
7.5.getQuestionAnswer
7.5.1功能
基于知道频道问题ID、回答ID获取对应问题的数据的回答
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getQuestionInfo&call_id=127323494&format=xml&bd_sig=sig-result&qid=54a9e997ade585b3e99481e59bbd7a62310900&aid=54a9e997ade585b3e99481e59bbd7a62310900
7.5.2参数
参数名
类型
描述
4.2.1系统级参数全体
qid
string
知道频道的问题ID
aid
string
知道频道的回答ID
7.5.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
questionInfo
问题内容数据,具体明细参考
answerInfo
回答内容数据
7.6.getUserInfo
7.6.1功能
基于频道用户的utype、uid和uname获取用户积分等详细信息
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getUserInfo&call_id=127323494&format=xml&bd_sig=sig-result&utype=baidu&uid=0&uname=username
7.6.2参数
参数名
类型
描述
4.2.1系统级参数全体
utype
string
频道使用的用户系统类型
uid
int
在频道登陆过的用户id(自有用户系统必填)
uname
string
在频道登陆过的用户名(XX用户系统必填)
7.6.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
personUrl
用户名片页地址
score
用户经验值
wealth
用户财富值
qcount
提问条数
account
回答条数
bestrate
被采纳为最佳的比例
level
用户在知道频道的级别
userTitle
用户在知道频道的头衔
isExpert
用户是否为专家用户,0不是,1是
expertLevel
专家用户专家级别
expertTitle
专家用户专家头衔
7.7.getUserQuestionList
7.7.1功能
基于频道用户的utype、uid和uname获取用户的提问列表信息
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getUserQuestionList&call_id=1276418994&format=xml&bd_sig=sig-result&cid=249&qstatus=0&page_no=2&page_size=25&utype=baidu&uname=coolaxis&uid=0
7.7.2参数
参数名
类型
描述
4.2.1系统级参数全体
4.2.2业务级参数全体
utype
string
频道使用的用户系统类型
uid
int
在频道登陆过的用户id(自有用户系统必填)
uname
string
在频道登陆过的用户名(XX用户系统必填)
7.7.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
id
问题ID
url
该问题在知道频道的URL
title
问题标题
cid
该问题在知道频道所属的分类ID
qstatus
问题状态0为待解决,1为已解决,2为已关闭
cname
该问题在知道频道所属的分类名称
createTime
问题创建时间(unix时间戳形式)
7.8.getUserAnswerList
7.8.1功能
基于频道用户的utype、uid和uname获取用户的回答问题列表信息
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&method=baidu.zhidao.getUserAnswerList&call_id=1276418994&format=xml&bd_sig=sig-result&cid=249&qstatus=0&page_no=2&page_size=25&utype=baidu&uname=coolaxis&uid=0
7.8.2参数
参数名
类型
描述
4.2.1系统级参数全体
4.2.2业务级参数全体
utype
string
频道使用的用户系统类型
uid
int
在频道登陆过的用户id(自有用户系统必填)
uname
string
在频道登陆过的用户名(XX用户系统必填)
7.8.3返回值
●ResponseXML示例
●ResponseXML标签说明
标签名
描述
id
问题ID
url
该问题在知道频道的URL
title
问题标题
cid
该问题在知道频道所属的分类ID
qstatus
问题状态0为待解决,1为已解决,2为已关闭
cname
该问题在知道频道所属的分类名称
createTime
问题创建时间(unix时间戳形式)
7.9.getRecommend
7.9.1功能
获取知道频道的精彩推荐信息
URLDemo:
:
//zhidao.xxx/restserver/zhidao?
api_key=1uMqYWpHo3MoLH&metho
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 百度 知道 开放 平台 openAPI 接口 规范 文档 V10