请教：百度知道，数据合作模式开发，大家有搞过的吗？

[alpha]

http://www.baidu.com/search/openiknow/index.html
公司和百度合作，公司的一个问答模块与知道模块接口合作。需要提交申请文档。
因为百度接口也是刚做的，分为，频道合作模式和数据库合作模式。
我们使用的是数据合作模式，但是百度只给了一个api，里面写的很简单。连个demo都没有。
而且只是php语言的。我们的网站是jsp的。
现在一头雾水不知道改如何下手。

[JavaAlpha]

楼主可以参考。

用户系统开放API接口开发文档 v2.1
百度知道研发组

文档声明：首先欢迎各合作站点加入百度开放知道平台，请各个合作站点技术人员认真仔细阅读该接口开发文档，接口开发完成后，请参考第3项中的check list中的描述步骤进行仔细确认，确保接口功能正常，减少后续联调反复的代价。感谢各个合作站点的有效配合！

1. 背景
在开放知道运作模式下，为了能够更好的接入合作站点的用户系统，第三方用户系统中的用户可以直接使用开放知道的服务。为了实现该功能效果，需要合作站点和开放知道一定的交互协作，共同认证识别合作站点用户的真实身份，记录用户积分、用户贡献以及页面展示。
2. 接口开发
为了完成用户身份验证，登陆等功能需求，主要需要合作站点提供以下4个接口：
2.1 接口一 用户登录
第三方需提供的功能简介：
1. 合作站点提供完整的登录页面
2. 用户在登录页面登录成功后需要生成唯一性的Token（映射用户身份），然后需要将该token保存在站点大域的cookie中（确保zhidao.xxx.com域名能够获取到该cookie），例如www.xxx.com
3. 由于用户名密码错误等原因导致的登陆失败，在登录页面中直接给予提示，引导用户成功登陆，登陆成功后需要能够进行页面回调
请求URL Demo：
http://login.xxx.com/login.jsp?callback=http://zhidao.xxx.com/login_finish
url格式合作站点可自行确定，但是回调参数名称需要和其它下面接口统一一致，例如callback
回调URL Demo：
http://zhidao.xxx.com/login_finish?token=XXXYYYZZZ （参数名称需要等于token）
回调URL从请求URL的callback参数中获取，需要携带token参数
执行流程：

Token生成可选方案：
1. 根据用户信息（uid、uname等）加密生成token，验证token时可反解出用户信息提供给应用
2. 随机生成唯一Token，然后维护token到用户身份的映射关系
合作站点可根据当前用户系统情况，考虑复用现有Cookie、DB维护映射关系等方案实现Token的生成、验证。Token生成后保存在站点大域的cookie下，供问答平台后续用户身份验证使用。

2.2 接口二 用户身份验证
功能描述：验证请求URL中token参数的值是否有效，如果无效则返回未登录标识，如果有效则返回该用户的用户名和用户ID。
注意：用户身份验证是服务器发起验证请求，不携带浏览器cookie等本地信息，用户系统验证token有效性仅根据GET参数中的token对应的值进行判断，请勿使用本地cookie中任何内容为辅助判定依据。否则会导致验证失败！
请求URL Demo：
http://login.xxx.com/auth.jsp?token=XXXYYYZZZ （参数名称需要等于token）
返回数据格式如下：

注：返回数据请直接将string输出至页面，且勿附带其它无效信息，用户名等中文请采用UTF-8编码
执行流程参见下图：


2.3 接口三 用户登出
功能描述：用户执行登出操作，参数携带之前用户登陆生成的token以及回调URL，用户系统处理登出后需要配合清理cookie中的token，然后回调URL。
请求URL Demo：
http://logout.xxx.com/logout.jsp?token=XXXYYYZZZ&callback=http://zhidao.xxx.com/user/exit

2.4 接口四 用户注册
功能描述：
1. 合作站点提供完整的注册页面
2. 用户注册成功后，需要自动进入登陆状态，并且支持回调指定页面，登陆细节同登陆接口一致，包括生成token以及写入cookie
请求URL Demo：
http://register.xxx.com/register.jsp?callback=http://zhidao.xxx.com/login_finish
回调URL Demo：
http://zhidao.xxx.com/login_finish?token=XXXYYYZZZ （参数名称需要等于token）

3. Check List
3.1 用户登陆接口
1. 浏览器中输入用户登陆接口URL，例如（xxx为贵网站域名）
http://login.xxx.com/login.jsp?callback=http://www.xxx.com ，正常情况下应该展示贵网站的用户登陆页面
2．在1中展示的登陆页面中进行用户登陆操作，如果登陆失败提示失败原因，让用户继续完成登陆，如果登陆成功，那么页面应该能够自动跳转至callback参数所指向的URL http://www.xxx.com ，并且跳转的url格式应该为http://www.xxx.com?token=AAABBBCCCDDD
AAABBBCCCDDD是贵网站根据uid uname等信息生成的token
3. 在2中提到的回调callback指定的页面http://www.xxx.com ，查看该大域下是否将token的信息写入了cookie中，如果cookie项存在，则表示正常，否则异常

3.2 用户身份验证接口
1. 基于3.1用户登陆接口的验证成功，我们能够在callback回调之后的url
http://www.xxx.com?token=AAABBBCCCDDD 以及cookie中查看到token的具体信息，然后使用用户身份验证接口组拼URL http://login.xxx.com/auth.jsp?token=XXXYYYZZZ ，在浏览器中输入该URL，如果用户身份验证接口正常，那么能够返回正确的querystring格式的字符串包含uid和uname，例如errno=0&uid=777&uname=gyk
2. 如果步骤1的检测方式通过，那么请将步骤1中的URL换一种浏览器或者换一台机器上进行再一次的验证，看返回结果是否仍然正确，包含uid uname信息并且格式正确，如果返回结果一致，则验证接口OK，否则异常
3． 如果我们随意使用一个无效的token进行请求验证，返回的querysting应该为errno=-1
4. 如果用户系统支持中文用户名，那么请确认返回的中文用户名字符编码为UTF-8

3.3 用户登出接口
1. 组拼登出接口的URL，例如
http://logout.xxx.com/logout.jsp?token=AAABBBCCCDDD&callback=http://www.xxx.com ，调用该接口后确认是否进行了页面的回调跳转，如果未进行跳转则功能异常
2. 如果页面回调跳转了，确认一下登录成功后保存的token cookie项是否仍然存在，如果被删除了，接口功能正常，如果cookie项依然存在，则接口功能异常

3.4 用户注册接口
注册功能接口与登录功能接口类似，注册成功相当于登录成功后的状态，处理过程和结果应该和登陆接口保持一致，按照登陆接口的check list校验确认即可。

[JavaAlpha]

百度知道OPEN API接口规范文档V1.1







系统名称 百度知道OPEN API服务接口
项目负责人
作者 耿艳坤
文档提交日期 2010-08-26












百度在线网络技术（北京）有限公司
(版权所有,翻版必究)






修改记录

No 修改后
版本号 修改内容简介 修改日期 修改人
1 1.0 百度知道OPEN API服务接口 2010-08-26 耿艳坤




































目 录
1 背景 4
2 规范适用对象说明 4
3 名词解释 4
4 请求数据包格式规范 4
4.1 URL 4
4.2 参数 4
4.2.1 系统级参数 4
4.2.2 业务级参数的通用约定 5
4.2.3 参数签名算法 5
5 响应数据包格式规范 6
5.1 XML输出格式 6
5.2 json输出格式 6
5.3 错误响应输出格式 7
6 错误码定义 7
7 API接口细则 8
7.1 baidu.zhidao.getQuestionList 8
7.1.1 功能 8
7.1.2 参数 8
7.1.3 返回值 8
7.2 baidu.zhidao.getQuestionSearch 9
7.2.1 功能 9
7.2.2 参数 9
7.2.3 返回值 9
7.3 baidu.zhidao.getQuestionInfo 10
7.3.1 功能 10
7.3.2 参数 10
7.3.3 返回值 10
7.4 baidu.zhidao.getQuestionAnswer 11
7.4.1 功能 11
7.4.2 参数 11
7.4.3 返回值 12
7.5 baidu.zhidao.question 12
7.5.1 功能 12
7.5.2 参数 12
7.5.3 返回值 12
7.6 baidu.zhidao.answer 13
7.6.1 功能 13
7.6.2 参数 13
7.6.3 返回值 13
8 第三方提供API接口细则 14
9 附件及参考资料 14


1 背景
本文旨在为第三方合作站点应用访问百度知道开放服务提供统一的HTTP接口调用与交互规范。
本文中描述的规范包括百度知道问题列表查询接口、检索查询接口、提问接口和回答接口。
2 规范适用对象说明
本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的Open API。
3 名词解释
 百度知道：http://zhidao.baidu.com
 API KEY：注册API合作时由百度的OPEN API平台分配的唯一标识一个应用的字符串，又称应用公钥
 API SECRET：注册API合作时由百度的OPEN API平台分配的应用密钥，用于平台与合作站点之间通信时的参数签名
4 请求数据包格式规范
4.1 URL
按照百度Open API规范，百度知道OPEN API提供如下REST风格的HTTP接口：
http://open.zhidao.baidu.com/restserver/zhidao?{query_string}
query_string由系统级参数部分和具体Open API调用参数部分组成，以key1=value&key2=value2&…表示，对于采用POST请求的Open API，query_string部分则是在POST请求体里。所有查询类的Open API接口既支持POST，也支持GET方式，提交类的OPEN API接口仅支持POST方式。
4.2 参数
4.2.1 系统级参数
以下参数是由百度Open API平台系统定义的，百度知道需要支持这些参数以便接入该平台提供开放接口。百度知道采用应用授权认证接口方式，合作初始百度知道代第三方站点申请应用分配api_key和参数签名密钥api_secret。
表格 4 1 API系统级参数
参数名 类型 是否必需 描述
api_key string 是 注册应用时分配到的api key
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 业务级参数的通用约定
百度知道遵守百度Open API规范中业务级通用参数的约定。
表格 4 2 业务级参数的通用约定
参数名 类型 描述
page_no Int 用于支持分页的api，默认为1，表示第几页
page_size Int 用于支持分页的api，表示每页返回多少条数据，默认以及上限为25
4.2.3 参数签名算法
参数签名生成算法采取如下方式（PHP版），其它语言根据注释描述完成等同功能：
//param_array是key-value形式的参数数组，不包括api_secret密钥本身
//secret是合作申请成功后分配的api_secret密钥
function generate_sig($param_array, $secret) {
$str = '';
//对param_array中的参数名称进行升序排序
ksort($param_array);
//按照如下格式转换数组为string格式
foreach ($param_array as $k=>$v) {
$str .= "$k=$v";
}
//string末端补充api_secret密钥
$str .= $secret;
//生成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输出可能为：
<questionList list="true">
<title><![CDATA[北京一共有几个区？]]></title>
<title><![CDATA[百度大厦的地址是什么？]]></title>
</questionList>
 接口的返回数据中，对象类型和普通数据类型数据（string，int，double，bool）对应的xml节点不包含list属性或者list属性值为false，节点标签名具有实际意义，与数据所描述的信息相符。例如，表示问题的数据对应的xml输出为：
<question list=”false”>
<title><![CDATA[百度大厦的地址是什么？]]></title>
<url><![CDATA[http://zhidao.baidu.com/question/133295964.html]]</url>
<content><![CDATA[如题，百度大厦地址在]]</ content >
</question>
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格式的错误响应包为如下格式：
<?xml version="1.0" encoding="UTF-8"?>
<baidu_zhidao_getQuestionList_response>
<error_code>101</error_code>
<error_msg>Invalid API key</error_msg>
<request_args list="true">
<arg>
<key><![CDATA[cid]]></key>
<value><![CDATA[249]]></value>
</arg>
<arg>
<key><![CDATA[method]]></key>
<value><![CDATA[baidu.zhidao.getQuestionLis]]></value>
</arg>
</request_args>
</ baidu_zhidao_getQuestionList_response >
Json格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串
6 错误码定义
百度开放知道OPEN API调用过程中可能会返回的错误码定义如下表所示：
error_code error_msg Description
0 Success 成功
1 Unknown error 未知错误
2 Service temporarily unavailable 后端服务暂时不可用
3 Unsupported openapi method Open api接口不被支持
4 Open api request limit reached 应用对open api接口的调用请求数达到上限
5 Unauthorized client IP address:%s open api调用端的IP未被授权
100 Invalid parameter 参数无效或缺失
101 Invalid API key Api key无效
103 Invalid call_id parameter Call_id参数无效或已被使用过
104 Incorrect signature 签名无效
105 Too many parameters 参数过多
106 Unsupported signature method 参数签名算法未被平台所支持
200 No permission to access data 没有权限访问数据
900 No such application exists 应用不存在
12001 Parameters format error 必选参数格式错误
12002 Answer for invalid question 提交回答的问题生命已结束
7 API接口细则
以下接口返回数据均是以XML格式为demo，JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。
7.1 baidu.zhidao.getQuestionList
7.1.1 功能
基于百度知道分类ID获取对应分类下的问题列表
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&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 业务级参数全体
cid int 百度知道的分类ID
qstatus int 问题状态 0为待解决 1为已解决
7.1.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
id 问题ID
url 该问题在百度知道的URL
title 问题标题
content 提问内容
cid 该问题在百度知道所属的分类ID
cname 该问题在百度知道所属的分类名称
7.2 baidu.zhidao.getQuestionSearch
7.2.1 功能
基于检索关键字在百度知道中搜索匹配的问题列表
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&method=baidu.zhidao.getQuestionSearch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京+百度大厦&qstatus=0
&page_no=2&page_size=25
7.2.2 参数
参数名 类型 描述
4.2.1 系统级参数全体
4.2.2 业务级参数全体
keywords string 检索关键字 多个检索关键字之间使用+号连接
qstatus int 问题状态 0为待解决 1为已解决
7.2.3 返回值
 Response XML 示例


 Response XML 标签说明
标签名 描述
id 问题ID
url 该问题在百度知道的URL
title 问题标题
content 提问内容
cid 该问题在百度知道所属的分类ID
cname 该问题在百度知道所属的分类名称
summary 已解决问题的最佳答案摘要
7.3 baidu.zhidao.getQuestionInfo
7.3.1 功能
基于百度知道问题ID获取对应问题的数据以及回答
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&method=baidu.zhidao.getQuestionInfo &call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482
7.3.2 参数
参数名 类型 描述
4.2.1 系统级参数全体
qid int 百度知道的问题ID
7.3.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
questionInfo 问题内容数据，具体明细参考7.1和7.2
bestAnswers 最佳答案列表
answers 普通答案列表
content 回答内容
cite 回答参考资料
7.4 baidu.zhidao.getQuestionAnswer
7.4.1 功能
基于百度知道问题ID、回答ID获取对应问题的数据的回答
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&method=baidu.zhidao.getQuestionInfo &call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482&aid=1232142352
7.4.2 参数
参数名 类型 描述
4.2.1 系统级参数全体
qid int 百度知道的问题ID
aid int 百度知道的回答ID
7.4.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
questionInfo 问题内容数据，具体明细参考7.1和7.2
answerInfo 回答内容数据
7.5 baidu.zhidao.question
7.5.1 功能
向百度知道进行提问
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao 参数全部为POST方式
7.5.2 参数
参数名 类型 描述
4.2.1 系统级参数全体api_key method call_id format bd_sig（POST）
title string POST字段问题标题
content string POST字段问题内容
utype string POST字段用户类型，例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid
uname string POST字段第三方账号系统uname
7.5.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述
qid 问题ID
7.6 baidu.zhidao.answer
7.6.1 功能
向百度知道的待解决问题进行回答
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao 参数全部为POST方式
7.6.2 参数
参数名 类型 描述
4.2.1 系统级参数全体api_key method call_id format bd_sig （POST）
qid string POST字段提供回答的问题ID
content string POST字段回答内容
cite string POST字段回答参考资料
utype string POST字段用户类型，例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid
uname string POST字段第三方账号系统uname
7.6.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述
qid 回答成功后返回的问题id
8 第三方提供API接口细则
使用提问API（baidu.zhidao.question）的第三方，其用户使用该API提交提问之后，如果知道平台上有用户对该提问进行了回答，那么是需要一种机制反馈给第三方API调用者，以便及时将回答反馈给提问的用户，解决用户的疑问。本章节描述提问下产生回答后，第三方需要提供的API接口规范格式和要求。所有回答相关的反馈输出字符编码均是UTF-8
需要第三方提供HTTP的接口，采用POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下：
参数名 类型 描述
method string 值为baidu.zhidao.feedback
qid int 问题ID，知道为int型
aid int 回答ID，知道为int型
utype string 提问用户的用户类型，例如baidu、renren、飞信
uid int 第三方账号系统uid
bd_sig string 参数签名
第三方基于接收到的qid和aid向平台发起请求，调用baidu.zhidao.getQuestionAnswer API接口获取对应提问下的回答信息。
第三方合作站点如果不采用消息提醒=》抓取回答内容的方式，可以选择下面这个直接接收回答数据的方法，仍然是HTTP接口，POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下：
参数名 类型 描述
method string 值为baidu.zhidao.feedAnswer
qid int 问题ID，知道为int型
aid int 回答ID，知道为int型
utype string 提问用户的用户类型，例如baidu、renren、wanmei
uid int 第三方账号系统uid
content string 回答内容
cite string 回答参考资料
bd_sig string 参数签名
第三方合作接收到平台的回答反馈后，需要按指定数据格式输出数据信息，输出数据格式为UTF-8编码的XML接口。具体数据格式为：
 Response XML 示例
baidu.zhidao.feedback接口返回:

baidu.zhidao.feedAnswer接口返回:

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述

上述两种POST HTTP接口，对于使用提问API的第三方，实现一种即可，应用注册申请时指明具体采用策略即可。
9 附件及参考资料

[JavaAlpha]

开放知道 API描述文档
[e-mail]

【接口一 分类问题列表】

数据格式：JSON

API输入格式demo
http://zhidao.xxxx.com/api/qlist?cid=1&lm=1

必要参数
cid 分类ID
lm 1为未解决 2为已解决

可选参数
rn（取值范围10至30）返回问题条数

注：如果cid指定为0，则不区分分类

API输出格式 (具体可参见demo url返回的数据)
PAGE_STATUS 整型，200为正常，其它为异常
level_arr 分类层次关系数组，cid=0时该项为null
cid 分类ID(整型)
cname 分类名称
cur_class 当前分类信息
cid 分类ID(整型)
cname 分类名称，cid=0时该项为””
question_arr 分类下问题数组
qid问题ID(加密串)
title 问题标题
qstatus 问题状态(1为未解决 2为已解决 3为已关闭)
create_time 提问时间(时间戳)
cid 问题所属分类ID(整型)
cname 问题所属分类名称
reward问题悬赏分数(整型)
answer_count 问题回答个数(整型)
ql_count 问题总数量
lm 问题状态(1为未解决 2为已解决)

【接口二 用户名片页】

数据格式：JSON

API输入格式demo
http://zhidao.xxxx.com/api/person?api_account_id=2&api_uid=4487931

必要参数
api_account_id 用户系统类型，uuu9用户类型为2
api_uid 用户ID(整型)

可选参数
rn（取值范围10至30）返回用户回答纪录条数

API输出格式(具体可参见demo url返回的数据)
PAGE_STATUS 整型，200为正常，其它为异常
ans_question 用户回答纪录数组
qid 问题ID(加密串)
title 问题标题
q_create_time 提问时间(时间戳)
a_create_time 回答时间(时间戳)
qstatus 问题状态(1为未解决 2为已解决 3为已关闭)
finish_time 问题被关闭/采纳时间(时间戳)
is_best 是否是最佳答案(0为非最佳，1为最佳)
reward 问题悬赏分数(整型)
answer_count 问题回答个数(整型)
count 该用户回答的总数(整型)
person 用户信息
account_id 用户账号类型(加密串)
site_id 应用类型ID(加密串)
uid (加密串)
uname 用户名
score 用户积分
wealth 暂不使用
q_count 用户提问总数
a_count 用户回答总数
best_count 用户最佳答案数
praise_count 暂不使用
is_blocked 该用户当前是否被封禁(0为非封禁 1为封禁)
admin_level 管理员权限(0为非管理员 1为管理员)
good_rate 用户回答采纳率
level 用户等级
level_ch 用户等级中文展示
head_title 用户头衔









百度知道OPEN API接口规范文档V1.1







系统名称 百度知道OPEN API服务接口
项目负责人
作者 耿艳坤
文档提交日期 2010-08-26












百度在线网络技术（北京）有限公司
(版权所有,翻版必究)






修改记录

No 修改后
版本号 修改内容简介 修改日期 修改人
1 1.0 百度知道OPEN API服务接口 2010-08-26 耿艳坤
2 1.1 增加采纳接口 2010-12-12 陈霖



































目 录
1 背景 5
2 规范适用对象说明 5
3 名词解释 5
4 请求数据包格式规范 5
4.1 URL 5
4.2 参数 5
4.2.1 系统级参数 5
4.2.2 业务级参数的通用约定 6
4.2.3 参数签名算法 6
5 响应数据包格式规范 7
5.1 XML输出格式 7
5.2 json输出格式 7
5.3 错误响应输出格式 8
6 错误码定义 8
7 API接口细则 9
7.1 baidu.zhidao.getQuestionList 9
7.1.1 功能 9
7.1.2 参数 9
7.1.3 返回值 10
7.2 baidu.zhidao.getQuestionSearch 10
7.2.1 功能 10
7.2.2 参数 10
7.2.3 返回值 11
7.3 baidu.zhidao.getQuestionInfo 11
7.3.1 功能 11
7.3.2 参数 11
7.3.3 返回值 11
7.4 baidu.zhidao.getQuestionAnswer 12
7.4.1 功能 12
7.4.2 参数 12
7.4.3 返回值 12
7.5 baidu.zhidao.question 13
7.5.1 功能 13
7.5.2 参数 13
7.5.3 返回值 13
7.6 baidu.zhidao.answer 14
7.6.1 功能 14
7.6.2 参数 14
7.6.3 返回值 14
7.7 baidu.zhidao.setBestAnswer 14
7.7.1 功能 14
7.7.2 参数 15
7.7.3 返回值 15
8 第三方提供API接口细则 15
9 附件及参考资料 17


1 背景
本文旨在为第三方合作站点应用访问百度知道开放服务提供统一的HTTP接口调用与交互规范。
本文中描述的规范包括百度知道问题列表查询接口、检索查询接口、提问接口和回答接口。
2 规范适用对象说明
本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的Open API。
3 名词解释
 百度知道：http://zhidao.baidu.com
 API KEY：注册API合作时由百度的OPEN API平台分配的唯一标识一个应用的字符串，又称应用公钥
 API SECRET：注册API合作时由百度的OPEN API平台分配的应用密钥，用于平台与合作站点之间通信时的参数签名
4 请求数据包格式规范
4.1 URL
按照百度Open API规范，百度知道OPEN API提供如下REST风格的HTTP接口：
http://open.zhidao.baidu.com/restserver/zhidao?{query_string}
query_string由系统级参数部分和具体Open API调用参数部分组成，以key1=value&key2=value2&…表示，对于采用POST请求的Open API，query_string部分则是在POST请求体里。所有查询类的Open API接口既支持POST，也支持GET方式，提交类的OPEN API接口仅支持POST方式。
4.2 参数
4.2.1 系统级参数
以下参数是由百度Open API平台系统定义的，百度知道需要支持这些参数以便接入该平台提供开放接口。百度知道采用应用授权认证接口方式，合作初始百度知道代第三方站点申请应用分配api_key和参数签名密钥api_secret。
表格 4 1 API系统级参数
参数名 类型 是否必需 描述
api_key string 是 注册应用时分配到的api key
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 业务级参数的通用约定
百度知道遵守百度Open API规范中业务级通用参数的约定。
表格 4 2 业务级参数的通用约定
参数名 类型 描述
page_no Int 用于支持分页的api，默认为1，表示第几页
page_size Int 用于支持分页的api，表示每页返回多少条数据，默认以及上限为25
4.2.3 参数签名算法
参数签名生成算法采取如下方式（PHP版），其它语言根据注释描述完成等同功能：
//param_array是key-value形式的参数数组，不包括api_secret密钥本身
//secret是合作申请成功后分配的api_secret密钥
function generate_sig($param_array, $secret) {
$str = '';
//对param_array中的参数名称进行升序排序
ksort($param_array);
//按照如下格式转换数组为string格式
foreach ($param_array as $k=>$v) {
$str .= "$k=$v";
}
//string末端补充api_secret密钥
$str .= $secret;
//生成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输出可能为：
<questionList list="true">
<title><![CDATA[北京一共有几个区？]]></title>
<title><![CDATA[百度大厦的地址是什么？]]></title>
</questionList>
 接口的返回数据中，对象类型和普通数据类型数据（string，int，double，bool）对应的xml节点不包含list属性或者list属性值为false，节点标签名具有实际意义，与数据所描述的信息相符。例如，表示问题的数据对应的xml输出为：
<question list=”false”>
<title><![CDATA[百度大厦的地址是什么？]]></title>
<url><![CDATA[http://zhidao.baidu.com/question/133295964.html]]</url>
<content><![CDATA[如题，百度大厦地址在]]</ content >
</question>
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格式的错误响应包为如下格式：
<?xml version="1.0" encoding="UTF-8"?>
<baidu_zhidao_getQuestionList_response>
<error_code>101</error_code>
<error_msg>Invalid API key</error_msg>
<request_args list="true">
<arg>
<key><![CDATA[cid]]></key>
<value><![CDATA[249]]></value>
</arg>
<arg>
<key><![CDATA[method]]></key>
<value><![CDATA[baidu.zhidao.getQuestionLis]]></value>
</arg>
</request_args>
</ baidu_zhidao_getQuestionList_response >
Json格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串
6 错误码定义
百度开放知道OPEN API调用过程中可能会返回的错误码定义如下表所示：
error_code error_msg Description
0 Success 成功
1 Unknown error 未知错误
2 Service temporarily unavailable 后端服务暂时不可用
3 Unsupported openapi method Open api接口不被支持
4 Open api request limit reached 应用对open api接口的调用请求数达到上限
5 Unauthorized client IP address:%s open api调用端的IP未被授权
100 Invalid parameter 参数无效或缺失
101 Invalid API key Api key无效
103 Invalid call_id parameter Call_id参数无效或已被使用过
104 Incorrect signature 签名无效
105 Too many parameters 参数过多
106 Unsupported signature method 参数签名算法未被平台所支持
200 No permission to access data 没有权限访问数据
900 No such application exists 应用不存在
12001 Parameters format error 必选参数格式错误
12002 Answer for invalid question 提交回答的问题生命已结束
12003 Query for invalid question status 查询问题状态错误
12004 Post str too long or short 提交字符串长度不合法
12005 Invalid qid or aid 所找问题、回答已失效或不存在
12006 Answer user is the asker or asked 回答用户是提问者或者已经回答过
12102 Invalid account system 无效的账户系统
7 API接口细则
以下接口返回数据均是以XML格式为demo，JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。

[alpha]

谢谢 熊猫。

[JavaAlpha]

7.1 baidu.zhidao.getQuestionList
7.1.1 功能
基于百度知道分类ID获取对应分类下的问题列表
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&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 业务级参数全体
cid int 百度知道的分类ID
qstatus int 问题状态 0为待解决 1为已解决
7.1.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
id 问题ID
url 该问题在百度知道的URL
title 问题标题
content 提问内容
cid 该问题在百度知道所属的分类ID
cname 该问题在百度知道所属的分类名称
7.2 baidu.zhidao.getQuestionSearch
7.2.1 功能
基于检索关键字在百度知道中搜索匹配的问题列表
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&method=baidu.zhidao.getQuestionSearch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京+百度大厦&qstatus=0
&page_no=2&page_size=25
7.2.2 参数
参数名 类型 描述
4.2.1 系统级参数全体
4.2.2 业务级参数全体
keywords string 检索关键字 多个检索关键字之间使用+号连接
qstatus int 问题状态 0为待解决 1为已解决
7.2.3 返回值
 Response XML 示例


 Response XML 标签说明
标签名 描述
id 问题ID
url 该问题在百度知道的URL
title 问题标题
content 提问内容
cid 该问题在百度知道所属的分类ID
cname 该问题在百度知道所属的分类名称
summary 已解决问题的最佳答案摘要
7.3 baidu.zhidao.getQuestionInfo
7.3.1 功能
基于百度知道问题ID获取对应问题的数据以及回答
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&method=baidu.zhidao.getQuestionInfo &call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482
7.3.2 参数
参数名 类型 描述
4.2.1 系统级参数全体
qid int 百度知道的问题ID
7.3.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
questionInfo 问题内容数据，具体明细参考7.1和7.2
bestAnswers 最佳答案列表
answers 普通答案列表
content 回答内容
cite 回答参考资料
7.4 baidu.zhidao.getQuestionAnswer
7.4.1 功能
基于百度知道问题ID、回答ID获取对应问题的数据的回答
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao?api_key=20000&method=baidu.zhidao.getQuestionInfo &call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482&aid=1232142352
7.4.2 参数
参数名 类型 描述
4.2.1 系统级参数全体
qid int 百度知道的问题ID
aid int 百度知道的回答ID
7.4.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
questionInfo 问题内容数据，具体明细参考7.1和7.2
answerInfo 回答内容数据
7.5 baidu.zhidao.question
7.5.1 功能
向百度知道进行提问
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao 参数全部为POST方式
7.5.2 参数
参数名 类型 描述
4.2.1 系统级参数全体api_key method call_id format bd_sig（POST）
title string POST字段问题标题
content string POST字段问题内容
utype string POST字段用户类型，例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid
uname string POST字段第三方账号系统uname
7.5.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述
qid 问题ID
7.6 baidu.zhidao.answer
7.6.1 功能
向百度知道的待解决问题进行回答
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao 参数全部为POST方式
7.6.2 参数
参数名 类型 描述
4.2.1 系统级参数全体api_key method call_id format bd_sig （POST）
qid string POST字段提供回答的问题ID
content string POST字段回答内容
cite string POST字段回答参考资料
utype string POST字段用户类型，例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid
uname string POST字段第三方账号系统uname
7.6.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述
qid 回答成功后返回的问题id
7.7 baidu.zhidao.setBestAnswer
7.7.1 功能
由提问用户对获取的回答进行采纳
URL Demo：
http://open.zhidao.baidu.com/restserver/zhidao 参数全部为POST方式
7.7.2 参数
参数名 类型 描述
4.2.1 系统级参数全体api_key method call_id format bd_sig （POST）
qid int POST字段问题qid
aid int POST字段回答id
thankWords string POST字段感谢语
utype string POST字段用户类型，例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid
uname string POST字段第三方账号系统uname
7.7.3 返回值
 Response XML 示例

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述
qid 回答成功后返回的问题id
8 第三方提供API接口细则
使用提问API（baidu.zhidao.question）的第三方，其用户使用该API提交提问之后，如果知道平台上有用户对该提问进行了回答，那么是需要一种机制反馈给第三方API调用者，以便及时将回答反馈给提问的用户，解决用户的疑问。本章节描述提问下产生回答后，第三方需要提供的API接口规范格式和要求。所有回答相关的反馈输出字符编码均是UTF-8
需要第三方提供HTTP的接口，采用POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下：
参数名 类型 描述
method string 值为baidu.zhidao.feedback
qid int 问题ID，知道为int型
aid int 回答ID，知道为int型
utype string 提问用户的用户类型，例如baidu、renren、飞信
uid int 第三方账号系统uid
bd_sig string 参数签名
第三方基于接收到的qid和aid向平台发起请求，调用baidu.zhidao.getQuestionAnswer API接口获取对应提问下的回答信息。
第三方合作站点如果不采用消息提醒=》抓取回答内容的方式，可以选择下面这个直接接收回答数据的方法，仍然是HTTP接口，POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下：
参数名 类型 描述
method string 值为baidu.zhidao.feedAnswer
qid int 问题ID，知道为int型
aid int 回答ID，知道为int型
utype string 提问用户的用户类型，例如baidu、renren、wanmei
uid int 第三方账号系统uid
content string 回答内容
cite string 回答参考资料
bd_sig string 参数签名
第三方合作接收到平台的回答反馈后，需要按指定数据格式输出数据信息，输出数据格式为UTF-8编码的XML接口。具体数据格式为：
 Response XML 示例
baidu.zhidao.feedback接口返回:

baidu.zhidao.feedAnswer接口返回:

 Response XML 标签说明
标签名 描述
error_code 错误号，0为成功
error_msg 错误描述

上述两种POST HTTP接口，对于使用提问API的第三方，实现一种即可，应用注册申请时指明具体采用策略即可。
9 附件及参考资料

[JavaAlpha]

开放知道 API描述文档
[e-mail]

【接口一 分类问题列表】

数据格式：JSON

API输入格式demo
http://zhidao.xxxx.com/api/qlist?cid=1&lm=1

必要参数
cid 分类ID
lm 1为未解决 2为已解决

可选参数
rn（取值范围10至30）返回问题条数

注：如果cid指定为0，则不区分分类

API输出格式 (具体可参见demo url返回的数据)
PAGE_STATUS 整型，200为正常，其它为异常
level_arr 分类层次关系数组，cid=0时该项为null
cid 分类ID(整型)
cname 分类名称
cur_class 当前分类信息
cid 分类ID(整型)
cname 分类名称，cid=0时该项为””
question_arr 分类下问题数组
qid问题ID(加密串)
title 问题标题
qstatus 问题状态(1为未解决 2为已解决 3为已关闭)
create_time 提问时间(时间戳)
cid 问题所属分类ID(整型)
cname 问题所属分类名称
reward问题悬赏分数(整型)
answer_count 问题回答个数(整型)
ql_count 问题总数量
lm 问题状态(1为未解决 2为已解决)

【接口二 用户名片页】

数据格式：JSON

API输入格式demo
http://zhidao.xxxx.com/api/person?api_account_id=2&api_uid=4487931

必要参数
api_account_id 用户系统类型，uuu9用户类型为2
api_uid 用户ID(整型)

可选参数
rn（取值范围10至30）返回用户回答纪录条数

API输出格式(具体可参见demo url返回的数据)
PAGE_STATUS 整型，200为正常，其它为异常
ans_question 用户回答纪录数组
qid 问题ID(加密串)
title 问题标题
q_create_time 提问时间(时间戳)
a_create_time 回答时间(时间戳)
qstatus 问题状态(1为未解决 2为已解决 3为已关闭)
finish_time 问题被关闭/采纳时间(时间戳)
is_best 是否是最佳答案(0为非最佳，1为最佳)
reward 问题悬赏分数(整型)
answer_count 问题回答个数(整型)
count 该用户回答的总数(整型)
person 用户信息
account_id 用户账号类型(加密串)
site_id 应用类型ID(加密串)
uid (加密串)
uname 用户名
score 用户积分
wealth 暂不使用
q_count 用户提问总数
a_count 用户回答总数
best_count 用户最佳答案数
praise_count 暂不使用
is_blocked 该用户当前是否被封禁(0为非封禁 1为封禁)
admin_level 管理员权限(0为非管理员 1为管理员)
good_rate 用户回答采纳率
level 用户等级
level_ch 用户等级中文展示
head_title 用户头衔

[liuxk1976]

文档都有，可是向百度返回答案的时候，baidu.zhidao.answer这个，老调不通。用表单POS提示未知错误。都没郁闷死了，那边还没技术对接的。

[wanting17]

是啊，我们也遇到同样问题：
向百度返回答案时，answer时，总提示Unknown error未知错误。

反复试了好多次，好像填写自己question时返回的问题qid，则成功！

不知是否百度知道对回答问题有什么限制！

[waiyi125]

200 No permission to access data 没有权限访问数据

是什么错误了

[alpha]

200 这个错误码 你搜下看看。

[笑离歌]

没看懂！我们也申请通过了！可是我去回答问题，下面也没有提示显示出我的logo啊！