精华版知道OPEN API接口规范文档10final.docx
- 文档编号:23310325
- 上传时间:2023-05-16
- 格式:DOCX
- 页数:15
- 大小:60.05KB
精华版知道OPEN API接口规范文档10final.docx
《精华版知道OPEN API接口规范文档10final.docx》由会员分享,可在线阅读,更多相关《精华版知道OPEN API接口规范文档10final.docx(15页珍藏版)》请在冰豆网上搜索。
精华版知道OPENAPI接口规范文档10final
[精华版]知道OPENAPI接口规范文档10_final
XX知道OPENAPI接口规范文档V1.0
系统名称XX知道OPENAPI服务接口
项目负责人
作者耿艳坤
文档提交日期2010-08-26
XX在线网络技术,北京,有限公司
(版权所有,翻版必究)
修改记录
修改后No修改内容简介修改日期修改人版本号
11.0XX知道OPENAPI服务接口2010-08-26耿艳坤
1背景...............................................................................................................52规范适用对象说明..........................................................................................53名词解释........................................................................................................54请求数据包格式规范......................................................................................5
4.1URL....................................................................................................5
4.2参数..................................................................................................6
4.2.1系统级参数...............................................................................6
4.2.2业务级参数的通用约定..............................................................6
4.2.3参数签名算法............................................................................65响应数据包格式规范......................................................................................7
5.1XML输出格式.....................................................................................7
5.2json输出格式...................................................................................8
5.3错误响应输出格式.............................................................................86错误码定义....................................................................................................97API接口细则..................................................................................................9
7.1baidu.zhidao.getQuestionList........................................................9
7.1.1功能..........................................................................................9
7.1.2参数..........................................................................................9
7.1.3返回值.....................................................................................10
7.2baidu.zhidao.getQuestionSearch....................................................10
7.2.1功能.........................................................................................10
7.2.2参数.........................................................................................10
7.2.3返回值.....................................................................................11
7.3baidu.zhidao.getQuestionInfo.......................................................11
7.3.1功能.........................................................................................11
7.3.2参数.........................................................................................11
7.3.3返回值.....................................................................................12
7.4baidu.zhidao.getQuestionAnswer....................................................12
7.4.1功能.........................................................................................12
7.4.2参数.........................................................................................13
7.4.3返回值.....................................................................................13
7.5baidu.zhidao.question....................................................................13
7.5.1功能.........................................................................................13
7.5.2参数.........................................................................................13
7.5.3返回值.....................................................................................14
7.6baidu.zhidao.answer.......................................................................14
7.6.1功能.........................................................................................14
7.6.2参数.........................................................................................14
7.6.3返回值.....................................................................................148第三方提供API接口细则..............................................................................159附件及参考资料............................................................................................16
1背景
本文旨在为第三方合作站点应用访问XX知道开放服务提供统一的HTTP接口调用与交互规范。
本文中描述的规范包括XX知道问题列表查询接口、检索查询接口、提问接口和回答接口。
2规范适用对象说明
本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的OpenAPI。
3名词解释
XX知道:
APIKEY:
注册API合作时由XX的OPENAPI平台分配的唯一标识一个应用的字符串~又
称应用公钥
APISECRET:
注册API合作时由XX的OPENAPI平台分配的应用密钥~用于平台与合作站
点之间通信时的参数签名
4请求数据包格式规范
4.1URL
按照XXOpenAPI规范~XX知道OPENAPI提供如下REST风格的HTTP接口:
{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。
表格4-1API系统级参数
参数名类型是否必需描述
api_keystring是注册应用时分配到的apikey
采取baidu.zhidao.getQuestionList这methodstring是样的命名空间方式制定方法名
时间戳~系统时间的秒值,同个应用的不call_iduint是同api请求的time值应该是递增的,用
于防replay攻击
formatstring否响应包格式~可以是xml,默认,或json
API调用请求包的编码类型~支持UTF-8iestring否和GBK
参数签名~对bd_sig外所有参数串的签bd_sigstring是名~包括业务级的参数。
4.2.2业务级参数的通用约定
XX知道遵守XXOpenAPI规范中业务级通用参数的约定。
表格4-2业务级参数的通用约定
参数名类型描述
page_noInt用于支持分页的api~默认为1~表示第几页
用于支持分页的api~表示每页返回多少条数据~默认以及page_sizeInt上限为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;
//生成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[]]
[CDATA[如题~XX大厦地址在]]
5.2json输出格式
API调用时如果传递format参数为json,大小写不敏感,~则正常响应包符合如下规范的json字符串:
http响应头中的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属性的对象组成
.getQuestionList接口时传递的参数api_key无效~例如~假设第三方应用调用baidu.zhidao
则其对应的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_codeerror_msgDescription
Success0成功
Unknownerror1未知错误
Servicetemporarilyunavailable2后端服务暂时不可用
Unsupportedopenapimethod3Openapi接口不被支持
应用对openapi接口的调用请求数Openapirequestlimitreached4达到上限
UnauthorizedclientIPaddress:
%s5openapi调用端的IP未被授权
Invalidparameter100参数无效或缺失
InvalidAPIkey101Apikey无效
Invalidcall_idparameter103Call_id参数无效或已被使用过
Incorrectsignature104签名无效
Toomanyparameters105参数过多
Unsupportedsignaturemethod106参数签名算法未被平台所支持
Nopermissiontoaccessdata200没有权限访问数据
Nosuchapplicationexists900应用不存在
Parametersformaterror12001必选参数格式错误
Answerforinvalidquestion12002提交回答的问题生命已结束7API接口细则
以下接口返回数据均是以XML格式为demo,JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。
7.1baidu.zhidao.getQuestionList
7.1.1功能
基于XX知道分类ID获取对应分类下的问题列表
URLDemo:
;method=baidu.zhidao.getQuestionList
&call_id=1276418994&format=xml&bd_sig=sig-result&cid=249&qstatus=0&page_no=2&page_size=25
7.1.2参数
参数名类型描述
4.2.1系统级参数全体
4.2.2业务级参数全体
cidintXX知道的分类IDqstatusint问题状态0为待解决1为已解决7.1.3返回值
ResponseXML示例
ResponseXML标签说明
标签名描述
id问题ID
url该问题在XX知道的URL
title问题标题
content提问内容
cid该问题在XX知道所属的分类ID
cname该问题在XX知道所属的分类名称7.2baidu.zhidao.getQuestionSearch7.2.1功能
基于检索关键字在XX知道中搜索匹配的问题列表URLDemo:
;method=baidu.zhidao.getQuestionSear
ch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京+XX大厦&qstatus=0
&page_no=2&page_size=25
7.2.2参数
参数名类型描述
4.2.1系统级参数全体
4.2.2业务级参数全体
string检索关键字多个检索关键字之间使用+号连接keywords
qstatusint问题状态0为待解决1为已解决7.2.3返回值
ResponseXML示例
ResponseXML标签说明
标签名描述
id问题ID
url该问题在XX知道的URL
title问题标题
content提问内容
cid该问题在XX知道所属的分类ID
cname该问题在XX知道所属的分类名称7.3baidu.zhidao.getQuestionInfo7.3.1功能
基于XX知道问题ID获取对应问题的数据以及回答URLDemo:
;method=baidu.zhidao.getQuestionInfo
&call_id=127323494&format=xml&bd_sig=sig-result&qid=1227274827.3.2参数
参数名类型描述
4.2.1系统级参数全体
qidintXX知道的问题ID
7.3.3返回值
ResponseXML示例
ResponseXML标签说明
标签名描述
questionInfo问题内容数据~具体明细参考7.1和7.2
bestAnswers最佳答案列表
answers普通答案列表
content回答内容
cite回答参考资料
pic_url回答贴图URL
7.4baidu.zhidao.getQuestionAnswer7.4.1功能
基于XX知道问题ID、回答ID获取对应问题的数据的回答URLDemo:
;method=baidu.zhidao.getQuestionInfo
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 精华版知道OPEN API接口规范文档10final 精华版 知道 OPEN API 接口 规范 文档 10 final