百度知道OPENAPI接口规范文档1.0_final

百度知道OPEN API接口规范文档v1.0百度百度知道OPEN AP接口规范文档 V1.0系统名称百度知道OPEN API服务接口I项目负责人作者耿艳坤文档提交日期2010-08-26百度在线网络技术（北京）有限公司（版权所有,翻版必究）百度在线网络技术（北京）有限公司-ii -百度知道OPEN API接口规范文档v1.0百IS修改记录No修改后 版本号修改内容简介修改日期修改人11.0百度知道OPEN API服务接口2010-08-26耿艳坤百度在线网络技术（北京）有限公司-3 -143525174.docBai溢百虞目录1 背景42 规范适用对象说明 43 名词解释44 请求数据包格式规范 44.1 URL44.2 参数44.2.1 系统级参数44.2.2 业务级参数的通用约定 54.2.3 参数签名算法55 响应数据包格式规范 65.1 XML输出格式65.2 json输出格式65.3 错误响应输出格式 76 错误码定义77 API接口细则87.1 baidu.zhidao.getQuesti on List 87.1.1 功能87.1.2 参数87.1.3 返回值87.2 baidu.zhidao.getQuesti on Search 97.2.1 功能97.2.2 参数97.2.3 返回值97.3 baidu.zhidao.getQuesti onlnfo 107.3.1 功能 107.3.2 参数 107.3.3 返回值 107.4 baidu.zhidao.getQuesti onAn swer 117.4.1 功能117.4.2 参数117.4.3 返回值 127.5 baidu.zhidao.questi on 127.5.1 功能 127.5.2 参数 127.5.3 返回值 127.6 baidu.zhidao.a nswer 137.6.1 功能 137.6.2 参数 137.6.3 返回值 138 第三方提供 API接口细则 149 附件及参考资料 151背景本文旨在为第三方合作站点应用访问百度知道开放服务提供统一的HTTP接口调用与交互规范。本文中描述的规范包括百度知道问题列表查询接口、检索查询接口、提问接口和回答接口。2规范适用对象说明本规范仅适用于由服务器端发起调用请求、API。POST提交数据以及 GET请求文本数据结果的 Open3名词解释百度知道：API KEY:注册API合作时由百度的 OPEN API平台分配的唯一标识一个应用的字符串，又 称应用公钥API SECRET注册API合作时由百度的 OPENAPI平台分配的应用密钥，用于平台与合作站 点之间通信时的参数签名4请求数据包格式规范4.1 URL按照百度 Open API规范，百度知道 OPEN API提供如下REST风格的HTTP接口： stringquery_stri ng由系统级参数部分和具体 Ope n API调用参数部分组成，以key1=value&key2=value2& 表示，对于采用 POST请求的 OpenAPI, query_string部分则是在 POST请求体里。所有查询类的Open API接口既支持POST也支持GET方式，提交类的 OPEN API接口仅支持POST方式。4.2参数4.2.1系统级参数以下参数是由百度 OpenAPI平台系统定义的，百度知道需要支持这些参数以便接入该平台提供开放接口。百度知道采用应用授权认证接口方式，合作初始百度知道代第三方站点申请应用分配api_key和参数签名密钥 api_secret 。表格4-1 API系统级参数参数名类型是否必需描述api_keystri ng是注册应用时分配到的api keymethodstri ng是采取 baidu.zhidao.getQuestionList这样的命名空间方式制定方法名call_idui nt是时间戳，系统时间的秒值，同个应用的不 同api请求的time值应该是递增的，用 于防replay 攻击formatstri ng否响应包格式，可以是xml （默认）或jsoniestri ng否API调用请求包的编码类型，支持UTF-8和GBKbd_sigstri ng是参数签名，对bd_sig外所有参数串的签 名，包括业务级的参数。4.2.2业务级参数的通用约定百度知道遵守百度 Open API规范中业务级通用参数的约定。表格4-2业务级参数的通用约定参数名类型描述page_noInt用于支持分页的api，默认为1，表示第几页page_sizeInt用于支持分页的 上限为25api，表示每页返回多少条数据，默认以及4.2.3参数签名算法参数签名生成算法采取如下方式（PHP版），其它语言根据注释描述完成等同功能：param_array 是key-value形式的参数数组，不包括 api_secret密钥本身/secret是合作申请成功后分配的api_secret 密钥function gen erate sig（$param array, $secret） $str = ”;II对param array中的参数名称进行升序排序ksort($param array);II按照如下格式转换数组为string格式foreach ($param array as $k=$v) |$str .= $k=$v;I/string末端补充 api_secret 密钥$str .= $secret;百度在线网络技术（北京）有限公司-9 -143525174.doc百虞/生成MD5为最终的数据签名return md5（$str）;注：密钥是百度知道分配给第三方应用的secret_key，该算法返回的结果便是系统级参数中的 bd_sig。5响应数据包格式规范响应数据包的格式由调用时传递的format参数指定（默认为xml格式），无论是xml格式还是json格式，输出内容都是UTF-8格式。目前，百度知道目前支持xml、json格式。5.1 XML输出格式文档编码格式UTF-8接口的返回数据中，数组对应的xml节点包含list= ”true ”属性，其子节点的标签名跟对应 的数据有联系，并且同个数组内的同级节点的标签名一致。例如表示问题标题列表对应的 xml输出可能为：vquestio nList list=true接口的返回数据中，对象类型和普通数据类型数据（string , int ，double ，bool ）对应的xml节点不包含list属性或者list属性值为false ，节点标签名具有实际意义，与数据所 描述的信息相符。例如，表示问题的数据对应的xml输出为：question list=false ”!CDATA n/133295964.html!CDATA如题，百度大厦地址在5.2 json输出格式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个属性组成，分别用于描述错误码，错误信息，以及调用Open API时所传递的所有参数的信息。request_args 属性是一个数组，由n个包含key和value属性的对象组成例如，假设第三方应用调用baidu.zhidao.getQuestionList接口时传递的参数api_key无效,则其对应的xml格式的错误响应包为如下格式：101 In valid API keyJson格式的字符串内容是 XML输出数据所对应的 PHP数组的标准JSON字符串6错误码定义百度开放知道 OPEN API调用过程中可能会返回的错误码定义如下表所示:error_codeerror_msgDescriptio n0Success成功1Unknown error未知错误2Service temporarily un available后端服务暂时不可用3Un supported ope napi methodOpen api接口不被支持百度在线网络技术（北京）有限公司-11 -143525174.doc百虞4Open api request limit reached应用对open api接口的调用请求数 达到上限5Un authorizedclie ntIP address:%sopen api调用端的IP未被授权100In valid parameter参数无效或缺失101In valid API keyApi key 无效103In valid call_id parameterCall_id参数无效或已被使用过104In correct sig nature签名无效105Too many parameters参数过多106Un supported sig nature method参数签名算法未被平台所支持200No permissi on to access data没有权限访问数据900No such applicati on exists应用不存在12001Parameters format error必选参数格式错误12002An swer for in valid questi on提交回答的冋题生命已结束7 API接口细则以下接口返回数据均是以 XML格式为demo,JSON格式的字符串内容是 XML输出数据所对应 的PHP数组的标准JSON字符串。7.1 baidu.zhidao.getQuestionList7.1.1 功能基于百度知道分类ID获取对应分类下的问题列表URL Demo: http:/ope n. on List& call_id=1276418994& format=xml&bd_sig=sig-result&cid=249&qstatus=O&page_no=2&page_size=257.1.2参数参数名类型描述4.2.1系统级参数全体4.2.2业务级参数全体cidint百度知道的分类IDqstatusint问题状态0为待解决1为已解决7.1.3返回值Response XML 示例 ： CDATA 133295364CD1TA百度大腹地址X/title CDATA百度大鹿地址Jx/contea1Response XML标签说明标签名描述id问题IDurl该问题在百度知道的 URLtitle问题标题content提问内容cid该冋题在百度知道所属的分类IDcn ame该问题在百度知道所属的分类名称7.2 baidu.zhidao.getQuestionSearch7.2.1功能基于检索关键字在百度知道中搜索匹配的问题列表URL Demo:http:/ope n. on Sear ch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京 + 百度大厦 &qstatus=O&page_ no=2&page_size=257.2.2参数参数名类型描述4.2.1系统级参数全体4.2.2业务级参数全体keywordsstri ng检索关键字多个检索关键字之间使用 +号连接qstatusint问题状态0为待解决1为已解决7.2.3返回值Response XML 示例vei：3ionrrl. Orr encodingsUTF-0rr? /question/133295964htJ. X/u.rL! CD ATA 百蘆大庫地址r LeResponse XML标签说明标签名描述id问题IDurl该问题在百度知道的 URLtitle问题标题content提问内容cid该冋题在百度知道所属的分类IDcn ame该问题在百度知道所属的分类名称7.3 baidu.zhidao.getQuestionlnfo7.3.1功能基于百度知道问题ID获取对应问题的数据以及回答URL Demo:http:/ope nlnfo& call_id=127323494&format=xml&bd_sig=sig-result&qid= 1227274827.3.2参数参数名类型描述4.2.1系统级参数全体qidint百度知道的冋题ID7.3.3返回值Response XML 示例bai.du_zhidao_gecQuestxonlnf o_r&sportse xm.lns=http: /openapibaidu com- xmlns:xsi=rrh.tt.p: /www m3 dieg/200JL/XML临cbeutL且一instance! CDATA 133295964/idO C/lbestAnsweO|Kanswer s liatrueanswer!CDATAdt京市羁提区上地十浙切母 坐地底口号线到西二旗站下年一宜柱西走五分钟就到了X/c皿t曰让 0gage baidu c o*/1/ image_c a tego ry / iaage/tik/zheng j laying .jpg answer list=rrfals已A Response XML标签说明标签名描述questio nlnfo问题内容数据，具体明细参考7.1和7.2bestA nswers最佳答案列表an swers普通答案列表content回答内容cite回答参考资料pic_url回答贴图URL7.4 baidu.zhidao.getQuestionAnswer7.4.1功能基于百度知道问题ID、回答ID获取对应问题的数据的回答URL Demo:http:/ope nlnfo& call_id=127323494& format=xml&bd_sig=sig-result&qid= 122727482&aid=12321423527.4.2参数参数名类型描述4.2.1系统级参数全体qidint百度知道的冋题IDaidint百度知道的回答ID7.4.3返回值Response XML 示例baldu_Ehidao_gtQuestionAnswei_response xulmshttp: /openapi. baidu. corr xmLns: xsi= Phttp: f /www. w3,org/2001 /XMLSchema-instance? !CDATA133295964JOnsweilnf List=rrEalserrc(Hiten/coaitenO Response XML标签说明标签名描述questio nlnfo问题内容数据，具体明细参考7.1和7.2an swerI nfo回答内容数据7.5 baidu.zhidao.question7.5.1功能向百度知道进行提问URL Demo:参数全部为 POST 方式7.5.2参数参数名类型描述4.2.1 系统级参数全体即i key method call idformat bd sig ( POSTtitlestri ngPOST字段冋题标题contentstri ngPOST字段问题内容utypestri ngPOST字段用户类型，例如baidu、renren、wanmeiuidintPOST字段第三方账号系统 uidun amestri ngPOST字段第三方账号系统 un ame7.5.3返回值Response XML 示例e 0succts3/riior$3S34543Response XML标签说明标签名描述error_code错误号，0为成功error_msg错误描述qid提问成功后返回的qid7.6 baidu.zhidao.answer7.6.1功能向百度知道的待解决问题进行回答URL Demo:参数全部为 POST 方式7.6.2参数参数名类型描述4.2.1 系统级参数全体即i_key method call_id format bd_sig ( POSTqidstri ngPOST字段提供回答的问题 IDcontentstri ngPOST字段回答内容citestri ngPOST字段回答参考资料pic_urlstri ngPOST字段回答的贴图utypestri ngPOST字段用户类型，例如baidu、renren、wanmeiuidintPOST字段第三方账号系统 uidun amestri ngPOST字段第三方账号系统 un ame7.6.3返回值Response XML 示例0succts3/eriiDr$8S34543Response XML标签说明标签名描述error code错误号，0为成功百度在线网络技术（北京）有限公司-17 -143525174.doc百虞error_msg错误描述qid回答成功后返回的问题id8第三方提供API接口细则使用提问API (baidu.zhidao.question)的第三方，其用户使用该 API提交提问之后，如果知道平台上有用户对该提问进行了回答，那么是需要一种机制反馈给第三方API调用者，以便及时将回答反馈给提问的用户，解决用户的疑问。本章节描述提问下产生回答后，第三方需要提供的API接口规范格式和要求。所有回答相关的反馈输出字符编码均是UTF-8需要第三方提供 HTTP的接口，采用POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下:参数名类型描述methodstri ng值为 baidu.zhidao.feedbackqidint问题ID，知道为int型aidint回答ID，知道为int型utypestri ng提冋用户的用户类型，例如baidu、renren、飞信uidint第三方账号系统uid第三方基于接收到的qid和aid向平台发起请求，调用 baidu.zhidao.getQuestionAnswer API接口获取对应提问下的回答信息。第三方合作站点如果不采用消息提醒=抓取回答内容的方式,可以选择下面这个直接接收回答百度在线网络技术（北京）有限公司-# -143525174.doc百虞百度在线网络技术（北京）有限公司-# -143525174.doc百虞4.2.3章节描述的算法一致，会数据的方法，仍然是 HTTP接口，POST方法，参数签名加密算法和使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下:参数名类型描述methodstri ng值为 baidu.zhidao.feedAnswerqidint问题ID，知道为int型aidint回答ID，知道为int型utypestri ng提冋用户的用户类型，例如baidu、renren、wanmeiuidint第三方账号系统uidcontentstri ng回答内容citestri ng回答参考资料pic urlstri ng回答的贴图URL第三方合作接收到平台的回答反馈后，需要按指定数据格式输出数据信息，输出数据格式为UTF-8编码的XML接口。具体数据格式为:Response XML 示例baid u. zhida o. feedback 接口返回 ceito j code0SLiccessbaid u. zhida o. feedAnswer接口返回?xm| version-1.0 encodingsUTF-S1?* terror code0Successerro_msg;*Response XML标签说明标签名描述error_code错误号，0为成功error_msg错误描述上述两种POST HTTP接口，对于使用提问 API的第三方，实现一种即可，应用注册申请时指明 具体采用策略即可。9附件及参考资料百度在线网络技术（北京）有限公司-19 -