API接口调用说明及示例第四次修订

/产品/项目名称保密级别邮件系统机密产品/项目版本最后更新日期81032014-09-12邮件系统V8接口文档北京亿中邮信息技术有限公司版权所有侵权必究仅供内部使用修订记录日期修订版本修改描述作者2012-11-150.1初稿刘畅2013-10-210.2初稿王永杰2014-04-220.3更新错误的5值傅春花2014-09-120.4重新编辑整理文档周盈妤目录\o"1-3"\h\u\l267521接口简介 267524\l145342认证概述 145345\l210452.1认证方式的分类 210455\l164042.2认证方式的选择 164046\l320352.3认证原理 320356\l210883认证方法详解及示例 210886\l31053.1 31056\l221183.2 221186\l259053.2.1的认证方法： 259056\l131693.2.2的认证方法： 131698\l200903.2.3申请会话： 200909\l191824接口调用示例 1918212\l41184.2调用 411812\l265024.2.1资源概述 2650212\l105444.2.2以用户的增删改查为例，示例各种调用步骤 1054413\l56845附表 5684171接口简介指邮件系统所提供的接口。调用接口流程图：申请申请获取认证认证认证认证认证认证（需要申请）调用接口调用接口为了保证调用的安全性等因素，要求调用方必须持有。此需要由调用方向方申请此。方在接受调用方申请后，会颁发以及一个与之配对的。调用方必须记录此以及。是提供方（例如部署了邮件系统的单位）颁发给调用方（例如需要获取邮件系统数据的系统）的身份识别串。此事一个邮件地址格式的字符串，例如：。提供方颁发给调用方身份识别串对应的秘钥。此是一个32字节的字符串，例如35c51333d1e9b36802c5d79b8。接口分为两大类：（1）用户提供（单点登录）的。（2）用于邮件资源操作的。2认证概述为保证的安全性，防止非法的调用，识别调用者身份的合法性，在调用过程中必须先进行认证。2.1认证方式的分类支持三种认证方式，分别是、和方式。是符合规范的标准认证方式，而和是自定义的规范。2.2认证方式的选择由于认证方式比较复杂，所以不建议使用认证方式，除非您的业务必须要求遵循方式认证。比安全性更高，但是也会更复杂一些，需要先申请会话。如果您对调用的安全性要求较高，那么建议您使用认证方式。如果您对调用的安全性要求不是非常高（比如邮件系统部署在内网，只在内网使用），那么可以使用认证方式。2.3认证原理认证的原理是：调用方在调用的同时需要附加传递认证信息（、、签名等），在接收到调用请求的同时，首先获取认证信息并进行认证，如果认证失败则给出错误提示，如果认证成功则继续处理调用请求，之后返回处理结果。不同的认证方式传递的认证信息有所不同，有的认证方式还需要先获取一些其他的安全认证数据用来生成认证信息，例如认证方式需要先申请会话。3认证方法详解及示例3.1标准的认证方式。详见官方文档以及5849。3.2认证方式对于和两种接口稍有不同，传递认证信息是通过的方式，则是通过把认证信息参数放到的头中传递。3.2.1的认证方法：将如下表格中的参数以参数的形式传递给。注意：由于是通过方式传递认证信息参数，所以所有的参数的值都必须要进行处理。参数名参数说明认证方式。为固定的值。系统当前的整数时间戳会话。此会话需要在调用之前申请。申请方法见申请会话。签名。算法：5(++++)的目标用户的邮件地址。此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这里列出。的认证完整示例 假设如下参数的值为：：：35c51333d1e9b36802c5d79b8：申请到的会话：548系统当前的整数时间戳：1262307600计算签名：5(35c51333d1e9b36802c5d79b81262307600548)计算的结果：46a8f76c21e86811d7b2260339b1此时得到方式传送所需的五个参数：:;:;:1262307600;:548;:46a8f76c21e86811d7b2260339b1;对五个参数分别作处理，得到如下结果：:;:40;:1262307600;:5483D;:46a8f76c21e86811d7b2260339b1;那么的请求为：3.2.2的认证方法：将如下表格中的参数放到的头中传递给。（的认证中，签名的计算不需要，此处与不同）注意：由于是通过头方式传递认证信息参数，所以所有的参数的值都必须要进行处理。参数名参数说明认证方式。为固定的值。系统当前的整数时间戳会话。此会话需要在调用之前申请。申请方法见申请会话。签名。算法：5(+++)的认证完整示例假设如下参数的值为：：：35c51333d1e9b36802c5d79b8申请到的会话：548系统当前的整数时间戳：1262307600计算签名：5(35c51333d1e9b36802c5d79b81262307600548)计算的结果：3e7f0e9a79c51f1a67d749908a3此时得到头中传送所需的五个参数：:;:;:1262307600;:548;:3e7f0e9a79c51f1a67d749908a3;对五个参数分别作处理，得到如下结果：:;:40;:1262307600;:5483D;:3e7f0e9a79c51f1a67d749908a3;那么（以获取的未读邮件数量为例）的请求数据包为：4011.0::"40","1262307600","5483D","3e7f0e9a79c51f1a67d749908a3"3.2.3申请会话：在认证方式中，和都需要提前申请用于传参和计算签名，申请会话的请求为：申请会话需要向上述发送一个为的请求，此请求必须包含如下表格中的参数。注意：由于是通过头方式传递认证信息参数，所以所有的参数的值都必须要进行处理。参数名参数说明系统当前的整数时间戳签名。算法：5(++)(非必需)的目标用户的邮件地址。（时需要此参数，不需要）上表中的前三个参数必须传递，除了必须传递的参数之外，还可以附加传递其它附加参数，所有的附加参数都会被记录在邮件系统中，以供下一步的验证使用（例如要求必须传递一个附加参数），但是要注意，附加的参数名不能以开头，以防止和必须传递的参数冲突。如果申请成功，会话将会被放到请求的应答中输出。成功或者失败的应答及说明详见附表1。获取完整示例假设如下参数的值为：：：35c51333d1e9b36802c5d79b8系统当前的整数时间戳：1262307600计算签名：5(35c51333d1e9b36802c5d79b81262307600)计算的结果：36b60456761a978387312此时得到所必须的三个参数：:;:1262307600;:36b60456761a978387312;申请时需要附加参数：:;对以上参数分别作处理，得到如下结果：:40;:1262307600;:3e7f0e9a79c51f1a67d749908a3;:40;（申请时需要）那么，请求数据包为：:::131436b60456761a978387312请求数据包为：:::131436b60456761a978387312403.3认证方式与认证方式的区别是认证信息参数为，并且不需要申请会话。也就是说，认证方式就是把认证方式中的参数变为，并且把申请会话的步骤去掉，同时把传递的认证参数中涉及会话的参数去掉（包括签名中的会话）。对于认证过程来说，除了没有会话，其余的处理与一致。4接口调用示例接口分为单点登陆的和邮件资源操作的。4.1单点登陆4.1.1请求和方法4.1.2请求参数及步骤详见的认证完整示例。4.2调用4.2.1资源概述以资源的形式提供调用。例如获取1这个用户的信件列表的资源地址为：1接口从资源类型来说分为两大类：1.资源列表类型，如域列表、用户列表等；2.具体的资源详情类型，如域详情、用户详情等。资源列表类型：为这类资源通常支持查询、分页，是资源详情的集合：：结果总数：开始位置：每页个数[""]：当前页[""]：第一页[""]：前一页[""]：下一页[""]：最后一页注意：资源列表类型默认返回10条数据，如需更改，可在请求后添加参数控制。资源列表返回条目控制参数名参数作用控制显示结果条目的数量控制返回资源列表的起始条目数例如：获取用户列表接口中，返回100条数据：？100返回从第20条开始的10条数据：？20返回从第20条开始的100条数据：？10020资源详情类型：为这类资源有固定标签，这些标签通常都有特殊含义，如：：目录、种类；：标题；：内容；：摘要。[""]：该资源的编辑地址。4.2.2以用户的增删改查为例，示例各种调用步骤用户的增删改查接口名称请求方式请求获取用户列表获取用户信息添加用户修改用户信息删除用户说明：为用户名。为用户所在的域。例如用户的邮件地址为，那么为，为。用户部分属性列表标签（根为）对应字段例子添加修改用户账户名√×用户真实名小明√√:创建时间，格式2010-04-20T10:30:53+08:00××密码√√调用用户操作示例<('','');定义认证信息('','e158163f9649b4f73b6e06c69f7');定义认证信息('','');定义邮件服务器$=();定义当前时间戳{{{认证信息$=;$='';申请，需要向发送一个为的请求，此请求必须如下中的三个参数：$=(''=>,''=>$,''=>5(..$),);$>(.'');$>();$>($);$>((''=>''));$>();$=$>();获取到会话认证传递认证信息是把认证信息参数放到的头中传递。认证信息参数包含,,,,.其中签名的算法为：5(+++)。$=5(..$.$);获取签名$=(''=>,''=>$,系统当前的整数时间戳''=>$,会话''=>$,签名);$=();($$>$v){$[]=$k.'="'.($v).'"';注意：由于是通过头方式传递认证信息参数，所以所有的参数的值都必须要进行处理。}$=$.''.(',',$);得到认证/*例如$的输出结果为："40","1262307600","5483D","3e7f0e9a79c51f1a67d749908a3"*/}}}{{{添加新用户方法$='1';$='1';$='100100100';$=0;$='';$='<"1.0""8"?>'.'<"""">'.'<>'.$.'<>'.'<>'.$.'<>'.'<>'.$.'<>'.'<>'.$.'<>'.'<>';$>(.''.$.'');根据接口的请求设置$>();根据接口的请求方式设置请求方法$>($);$>((''=>$));在头部传递认证信息$>();$>();返回'200'代表成功，应答代码列表参考附表2$>();成功时返回新用户数据，失败时提示错误原因。}}}{{{获取用户信息方法（资源详情类型）$='1';$='';$>(.''.$.''.$);根据接口的请求设置$>();根据接口的请求方式设置请求方法$>((''=>$,在头部传递认证信息''=>'',获取资源详情类型));$>();$>();返回'200'代表成功，应答代码列表参考附表2$>();成功时返回用户数据信息，失败时提示错误原因。}}}{{{获取用户列表方法（资源列表类型）$='';$>(.''.$.'');根据接口的请求设置$>();根据接口的请求方式设置请求方法$>((''=>$,在头部传递认证信息''=>'',获取资源列表类型));$>();$>();返回'200'代表成功，应答代码列表参考附表2$>();成功时返回用户列表数据信息，失败时提示错误原因。