本规范由动易(powereasy),动网(dvbbs),oblog三方联合制订和维护,其目的在于为不同的WEB应用按照统一的规范开发用户通行接口,以便实现不同WEB应用之间的用户数据同步。
本规范不限制WEB应用开发所使用的平台、开发语言、数据库,可以适用于任何基于B/S架构的WEB应用。只要按照本规范提供完整接口和数据处理支持的WEB应用,均可称“支持PDO1.0”。
支持本规范的所有WEB应用,其技术文档中应该提供对本规范中的元素支持程度的详细说明,以供其它WEB应用开发人员以及进行二次开发的用户参考。
请求包必须是一个构造良好的xml文档,以post方式由XMLHttpRequest对象发送。
为了避免不同编码下的乱码,该xml中的文本应该用DOM创建而不能用字符串形式创建。
请求中的蓝色斜体部分在实际运用时要由实际值替代。每个元素的详细定义和数据格式参考“元素列表”,直接写出元素名的元素为所有请求包都必须提供的数据。
POST HTTP/1.1
Content-Type: text/xml; charset=gb2312
<?xml version="1.0" encoding="gb2312"?>
<root>
<appid>程序标识</appid>
<action>操作类型</action>
<syskey>安全码</syskey>
<username>用户名</username>
<可选元素列表 />
</root>
响应包必须是一个构造良好的xml文档。
为了避免不同编码下的乱码,该xml中的文本应该用DOM创建而不能用字符串形式创建。
请求中的蓝色斜体部分在实际运用时要由实际值替代。每个元素的详细定义和数据格式参考“元素列表”,直接写出元素名的元素为所有请求包都必须提供的数据。
当操作状态为失败时,必须提供具体的错误说明。其它情况下,根据具体的操作类型和定义决定body及其子元素。
HTTP/1.1 200 OK
Content-Type: text/xml; charset=gb2312
Content-Length: length
<?xml version="1.0" encoding="gb2312"?>
<root>
<appid>程序标识</appid>
<status>操作结果</status>
<needcookie>是否需要写cookie</needcookie>
<body>
<message>操作不成功时的错误说明</message>
<可选元素列表 />
</body>
</root>
类别 | 元素名称 | 数据格式 | 可选值 | 使用方式 | 备注 |
---|---|---|---|---|---|
整 合 所 需 字 段 |
root | -- | -- | 通用 | 根元素 |
appid | string | dvbbs powereasy oblog other |
通用 | 程序标识 | |
action | string | checkname reguser login update delete getinfo |
请求包 | 操作类型 | |
syskey | string | 接口安全码 | 请求包 | 安全校验码 | |
status | integer | 0=操作完成 1=操作失败 |
返回包 | 操作结果 | |
body | string| nodelist |
-- | 返回包 | 响应信息或数据 | |
message | string | -- | 返回包 | 操作失败时返回 说明信息。 |
|
needcookie | integer | 0=不需要(默认) 1=需要 |
返回包 | 是否需要写cookie | |
username | string | -- | 请求包 | 用户名 | |
password | string | -- | 请求包 | 用户密码 (未加密) |
|
string | -- | 通用 | 电子邮件 | ||
question | string | -- | 通用 | 密码提示问题 | |
answer | string | -- | 通用 | 密码提示答案 (未加密) |
|
savecookie | string | 0=不记录(默认) 1=一周 2=一月 3=一年 |
通用 | cookies保存时间 | |
用 户 基 本 信 息 |
truename | string | -- | 通用 | 真实姓名 |
gender | string | 0=女 1=男 2=保密 |
通用 | 性别 | |
birthday | date | -- | 通用 | 生日 | |
integer | -- | 通用 | QQ号 | ||
msn | string | -- | 通用 | MSN帐号 | |
mobile | string | -- | 通用 | 移动电话 | |
telephone | string | -- | 通用 | 固定电话 | |
address | string | -- | 通用 | 通讯地址 | |
zipcode | string | -- | 通用 | 邮政编码 | |
homepage | string | -- | 通用 | 个人主页 | |
userip | string | -- | 通用 | 用户IP地址 | |
用 户 属 性 |
jointime | datatime | -- | 通用 | 注册日期 |
experience | integer | -- | 通用 | 经验值 | |
ticket | integer | -- | 通用 | 可消费积分 | |
valuation | integer | -- | 通用 | 贡献值 | |
balance | double | -- | 通用 | 现金余额 | |
posts | integer | -- | 通用 | 发表信息数 | |
userstatus | integer | 0=正常 1=锁定 2=屏蔽 3=禁止 4=待验证 |
通用 | 用户状态 |
本规范定义的元素共分为三组,其中第一组为实现整合通行所有程序必须支持的元素,第二、三组为各程序开发人员根据自己的情况可以自行决定是否支持的元素。
第二三组元素的主要作用在于方便利用整合接口进行跨程序的扩展功能开发,在正常情况下。
整合接口提供的各种操作可以提供或者不提供这两组元素,由开发人员自决,但是提供整合接口支持的各程序应当公布提供自己程序对扩展元素的支持程度和细节,以便其它程序的开发人员以及有能力的用户开发插件参考。为此在操作类别中增加了getinfo这一项,当向一个程序发送类型为getinfo的请求时,被请求方应当按照自己公布的支持情况返回尽可能多的信息以供共享利用。
元素中所有的元素名严格区分大小写,规定所有元素必须使用小写字母。用灰色显示的元素为尚在讨论中的元素,在正式规范中可能会被取消。
接口安全码“syskey”是用来检验程序间传输的数据来源合法性的依据。syskey元素是一个文本元素,值为一个定长32字节的字符串。该字符串由当前传输中包含的用户名和
各程序接口配置文件中用户定义的密钥连接起来,再进行16位MD5加密得出。如:
Set DvApi_Obj = New DvApi
DvApi_Obj.NodeValue "action","login",0,False
DvApi_Obj.NodeValue "username",UserName,1,False
Md5OLD = 1
SysKey = Md5(DvApi_Obj.XmlNode("username")&DvApi_SysKey,16)
Md5OLD = 0
DvApi_Obj.NodeValue "syskey",SysKey,0,False
以下部分对action元素的各项值对应的操作做出统一规定,格式为:
操作类型(必须元素1,必须元素2...)
每个操作的定义之后,对该操作所实现的功能和返回值做具体说明。其中appid、syskey、username为所有请求操作必须提供的参数,在定义中予以省略。返回操作中的xml均不包含syskey、username两个元素。
返回值中status不等于0的,返回值必须包括body元素及其子元素messenge。
定义:checkname()
作用:对请求中提供的用户名及email(如果有的话)进行验证,检查是否符合注册要求。
定义:reguser(password,email,question,answer)
作用:利用请求中提供的用户信息,进行用户注册。
定义:login(password)
作用:利用请求中提供的用户名、密码和cookies选项(默认为0,不保存)为用户登录。
定义:update()
作用:利用请求中提供的信息来更新用户资料。
定义:delete()
作用:根据请求中提供的用户名,对用户进行删除,当有多个用户时,用下面的形式提交(这里与其他操作有不同,接受方应当注意判断处理):
<username>用户名1,用户名2,用户名3</username>
定义:getinfo()
作用:检索请求中指定的用户的信息,成功时返回本规范支持的所有元素,对于没有对应字段的元素值,返回空元素,但不能省略。
为了解决跨站同步登陆,接收请求的检验方在响应请求的接口文件中,必须增加处理Cookie的逻辑,当检测到QueryString中包含数据时,说明是对Cookies操作的请求,要完成下列工作:
1.从Request.QueryString中提取四个参数:syskey,username,password,savecookie;
2.利用username和syskey,进行安全码验证,验证成功,则利用username和password,根据savecookie的值,处理本地cookie,使指定用户处于登陆状态。
3.完成,无需返回任何信息。
发送请求方解析检验方返回的xml数据说明可以登陆成功时,则应当构造一个script脚本调用,输出到页面的HTML代码。 当password为空表示注销COOKIE信息。
该脚本的路径为:
接口文件URL?syskey=16位安全码&username=用户名&password=加密的用户密码&savecookie=Cookie保存选项
工作组成员:悟空(动网)、感觉(Oblog)、阿泰(oblog)、nt2003(动易)、小李刀刀(动易)
最后修订日期:2006-03-29