API接口调用说明及示例第四次修订.docx
产品顽目名称保留级别邮件系统机密产品;1页目版本最终更新日期81032014-09-12邮件系统V8接口文档1僚亿中印信息技术有限公司版权全部侵权必究仅供内部运用修订记录日期修订版本修改描述作者2012-11-150.1初稿刘畅2013-10-210.2初稿王永杰2014-04-220.3更新错误的5值傅春花2014-09-120.4*S三整理文档周盈妤1接口简介未指定书签.2认证财-g!未指定书签.2.1 认iEM分类未指定书签.2.2 认防式的腼-躯!未指定书签.2.3 iuHJS三««!未指定书签.3认证方法详解及示例-错误!未指定书签.3.1 错误!未指定书签.3.2 躯!未指定书签。3.2.1 的认证方法：IB误!未指定书签.3.2.2 的认证方法：-错误!未指定书签。3.2.3 申35i三:未指定书签.4接口调用示例-错误!未指定书签。4.2调用««!未指定书签.4.2.1 资源螃-附!未指定书签.4.2.2 以用户的熠制改宜为例，示例各种调I用步骤错误!未指定书签.5附表-蹒!未指定书签.1接口简介指邮件系统所供应的接口.调用接口流程图：为了保证调用的平安性等因素，要求园用方必需持有.此须要由调用方向方申请此.方在接受调用方申请后,会颁发以及一个与之配对的.调用方必需记录此以及,是供应方（例如部署了由M牛系统的单位）颁发给调用方（例如须要获得邮件系统数据的系统）的身份识别串.此事一个郃件地址格式的字符串，例如：供应方颁发给调用方身份识别串对应的秘钥。此是一个32字节的字符串，例如35c51333dle9b36802c5d79b8.接口分为两大类：（1）用户供应（单点登录）的.（2）用于邮件资源操作的.2认证概述为保证的平安性，防止非法的调用.识另腿用者身份的合法性，在调用过程中必需先进行认证。2.1 认证方式的分类支持三种认证方式，分别是、和方式.是符合规范的凉准认证方式，而和是自定义的规范。2.2 认证方式的选择由于认证方式比较困难，所以不建议运用认证方式，除非您的业务必须要求通循方式认证.比平安性更高,但是也会更困难一些,须要先申请会话.钱如您对调用的平安性要求较高，那么建议您运用认证方式.假如您对调用的平安性要求不是特别高（比如部件系统部署在内网，只在内网运用），刃必可以运用认证方式。2.3 认证原理认证的原理是：调用方在调用的同时须要附加传递认证信息（、签名等），在接收到调用恳求的同时，首先获得认证信息并进行认证，假如认证失败剜给出错误提示，假如认证胜利则按蓿处理调用恳求，之后返回处理结果。不同的认证方式传递的认证信息有所不同,有的认证方式还须要湖得一些其他的平安认证数据用来生成认证信息，例如认证方式须要先申请会话.3认证方法详解及示例3.1标准的认证方式,详见官方文档以及5849.3.2认证方式对于和两种接口稍有不同,传递认证信息是通过的方式，则是通过把认证信息参数放到的头中传递.3.2.1 的认证方法：格如下表格中的参数以参数的形式传递给.留意：由于是通过方式传递认证信息参数，所以全部的参数的值都必须要进行处理.参数名参数说明认证方定为固定的伯.系统当前的整数时间St会话,此会话须要在调用之前申湾.申请方法见申请会话.签名.JS法：5(+)的目标用户的邮件地址.此整数并不是认证信息参数,但是由于在计算签名的时候须要用到，所以这这里列出.的认证完整硒保设如下音数的佰为：:35<51333dle9b36802c5d79b8申谓到的会话：548系统当前的整数时间截1262307600计舞签名：计算的结果：46a8f76<21e86811d7b2260339bl此时得到方式传送所需的五个卷数：12623076;：548;:468f76<21e86811d7b2260339bl;对五个参数分别作处理,得到如下结果：40；:1262307600;:S483D;:46a8f76c21e86811d7b2260339bl;那么的思来为：3.2.2 的认证方法：将如下表格中的卷数放到的头中传递给,（的认证中，签名的计算不须要，此处与不留意：由于是通过头方式传递认证信息?所以全部的参:都必须要进行处理.参数名参数说明认证方式.为固定的<S.系统当前的整数时间战会话.此会话须要在魂用之前申请.申谓方法见申请会话.签名.算法：5(+)的认证完整初保设如下段数的佰为:35<51333dle9b368O2c5d79b8申请到的会话：548系统当前的整数时间彼12623076计算签名：计算旌果：3e7fOe9a79c5Hla67d7499O8a3牝时到头中传送所需的五个图数：1262307600;:S48;:3e7fOe9a79c51fla67d749908a3;对五个参数分别作处理,得到如下结果：40;:1262307600;：5483D：3e7f0e9a79c51fla67d749908a3;那么(以轶得的未注邮件数也为例)的总求数据包为：4011.0：,40,1262307600,5483D-.3e7f0e9a79c51fla67d749908a3在认证方式中，和都须要提前申请用于传参和计算签名，申请会话的恳求为:申请会话须要向上述发送一个为的恳求，此恳求必需包含如下表格中的参数.留意：由于是通过头方式传递认证信息参数厮以全部的参数的值都必须要进行处理.参数名参数说明系统当前的整数时间St三.管法：5（+）（非必需）的目标用户的邮件地址.（时须要此叁数，不须要）上表中的前三个卷数必需传递，除了必需传递的参数之外，还可以附加传递其它附加参数,全部的附加参数都会被记录在邮件系统中，以供下一步的验证运用（例如要求必需传递一个附加参数）,但是要出意，附加的参数名不能以开头，以防止和必需传递的参数冲突.假如申请胜利，会话将会被放到恳求的应答中输出.胜利或者失败的应答及说明详见附表1.获得完整示例假设如下整数的值为：:35<51333dle9b36802c5d79b8系统当前的整数时间戢,1262307600计算签名：5（35c5B33dle9b36802c5d79b81262307600）计典的结果:36b60456761a978387312此时得到所必需的三个徐数:1262307600;：36b60456761a978387312;申清时须要酹力映数：对以上参数分别作处理，得到如下结果:40；：12623076;:3e7fOe9a79c51fla67d7499O8a3；：40；（申请时须要）那么，恳求数据包为：:131436b60456761a978387312忸求蜘三包为：:131436b60456761a9783873124033认证方式与认证方式的区分是认证信息参数为，并且不须要申请会话.也就是说，认证方式就是把认证E!；中的参数变为,并且把申请会话的步噱去掉，同时把传递的认证参数中涉及会话的参数去掉（包括签名中的会话）.对于认证过程来说，除了没有会话，其余的处理与一样.4接口调用示例接口分为单点登陆的和蜩牛资源操作的.4.1 单点登陆4.1.1 恳求和方法4.1.2 恳求参数及步骤详见的认证完整示例.4.2 调用4.2.1 资源概述以资源的形式供应调用,例如获得1这个用户的信件列表的资源地址为：1接口从资源类型来说分为两大类：1.资源列表类型，如域列表、用户列表等；4.2.2 资源详情类型，如域详情、用户详情等.斐源列表类型：为这类资源通常支持直询、分页，是资源详情的集合：:结果总数:起用立置:每页个数n：当前页(-J：第一页(,'：前一页n：下一页：最终一页版.意：资源列表类型默认返回10条数据，如需更改，可在恳求后添加参数限制.资源列表返回条目限制参数名参数作用限制显示结果条目的数量限制返回资源列表的起始条目数例如：获得用户列表接口中，返回100条数据：?100返回从第20条起先的10条数据：?20返回从第20条起先的100条数据：?10020资源详情类型：为这类资源有固定标签，这些标签通常都有特别含义，如：书目、种类；:标款；：内容；:摘要."：该资源的编辑地址.4.2.3 以用户的增删改查为例，示例各种调用步骤用户的增删改查接口名称恳求方式恳求获得用户列表获得用户信息添加用户修改用户信息SBJ除用户说明：为用户名.为用户所在的域.例如用户的邮件地址为，那么为，力.用户部分属性列表标签(根为)对应字段例子添加修改用户账户名X用户Jl实名小明创ii时间，格式2010-04-20110:30:5××3÷0800密码调用用户操作示例f");定义认证信息C.el58163f%49b4f73b6eO6c69f7);定义认ir二C.")；定义邮件服务髓$=0；定义当前时I礴«认证信息$="：申请,须要向发送为的寻求，此恳求必需如下中的三个卷故：$=("=>,"=>$,"=>5(.$),)；$>(.")；$>0；S>(三);$>«,>=>")；$>0；$三$>();荻得到会话认证传递认证信息是把认证信息参数放至购头中传递.认证信息螟包含,，.其中签名的想法为：5(+)$=5(.$.$)；获得签名$=("=>."=>$.系疑当前的找数时诃战"=>$,会话"=>$,密名)；$=0；(SS>Sv)$0=Sk.'=".(Sv).'；：由于是通过头方式传递认Sl,所以锚的参数的他航颁要进行处理.)$=得到认证/,例如S的输出结果为:MO-.1262307600，,5483D,3e7f0e9a79c51fla67d749908a37(添加新用户方法S=T；$='1'；$=,100100100,;$=,<,1.0,87>'.,<>>；依酶口的EW依受接口的患求方式设置恳求方法$>($);$>(r=>$);在头拿传递认证信息$>0；S>0;JSS200ItSK利,陆帕2S>0;.由.)»（获得用户信息方法（资谀详情臭兔）$='1'；$>（.".$.".$）；a三接口的患求设，$>0；依据接口的总求方式iSJB求方法在头部传递认证信息-=>.获组资源详情类空）；$>0；$>o；,2oo,tmm,*fw三2S>0;酥蹄SEl用，S3,失败时撞示镯n岫.
