产品/项目名称Product/Project Name 保密级别Confidentiality LeveleYou邮件系统机密产品/项目版本Product/Project Version 最后更新日期Last Update8103 2014-09-12 eYou邮件系统V8接口文档北京亿中邮信息技术有限公司All Rights Reserved 版权所有侵权必究仅供内部使用Revision Record 修订记录Date 日期Revision Version修订版本Change Description修改描述Author作者2012-11-15 0.1 初稿刘畅2013-10-21 0.2 初稿王永杰2014-04-22 0.3 更新错误的md5值傅春花2014-09-12 0.4 重新编辑整理文档周盈妤目录1 API接口简介------------------------------------------------------------------------ 42 API认证概述------------------------------------------------------------------------ 52.1 认证方式的分类-------------------------------------------------------------- 52.2 认证方式的选择-------------------------------------------------------------- 52.3 认证原理 --------------------------------------------------------------------- 53 认证方法详解及示例 ---------------------------------------------------------------- 63.1 OAuth ----------------------------------------------------------------------- 63.2 eYouAuth -------------------------------------------------------------------- 63.2.1 SSO API的eYouAuth认证方法： ------------------------------------- 63.2.2 Feed API的eYouAuth认证方法： ------------------------------------ 73.2.3 申请会话Token：------------------------------------------------------ 94 API接口调用示例 ------------------------------------------------------------------ 114.2 Feed API调用 ---------------------------------------------------------- 114.2.1 资源概述-------------------------------------------------------------- 114.2.2 以用户的增删改查为例，示例各种Feed API调用步骤---------------- 135 附表-------------------------------------------------------------------------------- 171 API 接口简介API 指eYou 邮件系统所提供的接口。
调用接口流程图：为了保证 API 调用的安全性等因素，eYouMail API 要求调用方必须持有 API KEY 。
此 API KEY 需要由调用方向 eYouMail 方申请此。
eYouMail 方在接受调用方申请后，会颁发 API KEY 以及一个与之配对的 API SECRET 。
调用方必须记录此 API KEY 以及 API SECTET 。
API KEY 是API 提供方（例如部署了eYou 邮件系统的单位）颁发给调用方（例如需要获取eYou 邮件系统数据的OA 系统）的身份识别串API KEY 。
此API KEY 事一个邮件地址格式的字符串，例如：apitest@ 。
API 提供方颁发给调用方身份识别串对应的秘钥。
此API_SECRET 是一个32字节的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。
API 接口分为两大类： （1）用户提供SSO （单点登录）的SSO API 。
（2）用于邮件资源操作的Feed API 。
申请 API KEY 获取 API SECRETOAuth 认证eYouAuth 认证（需要申请token ）eYouSimpleAuth 认证调用API 接口 SSO API Feed API2 API认证概述为保证API的安全性，防止非法的调用，识别调用者身份的合法性，在调用过程中必须先进行API认证。
2.1 认证方式的分类API支持三种认证方式，分别是OAuth、eYouAuth和eYouSimpleAuth方式。
OAuth是符合RFC规范的标准认证方式，而eYouAuth和eYouSimpleAuth是eYou自定义的规范。
2.2 认证方式的选择由于OAuth认证方式比较复杂，所以不建议使用OAuth认证方式，除非您的业务必须要求遵循OAuth方式认证。
eYouAuth比eYouSimpleAuth安全性更高，但是也会更复杂一些，需要先申请会话Token。
如果您对API调用的安全性要求较高，那么建议您使用eYouAuth认证方式。
如果您对API调用的安全性要求不是非常高（比如邮件系统部署在内网，只在内网使用），那么可以使用eYouSimpleAuth认证方式。
2.3 认证原理API认证的原理是：调用方在调用API的同时需要附加传递认证信息（API_KEY、API_SECRET、签名等），API在接收到调用请求的同时，首先获取认证信息并进行认证，如果认证失败则给出错误提示，如果认证成功则继续处理调用请求，之后返回处理结果。
不同的认证方式传递的认证信息有所不同，有的认证方式还需要先获取一些其他的安全认证数据用来生成认证信息，例如eYouAuth认证方式需要先申请会话Token。
3 认证方法详解及示例3.1 OAuth标准的OAuth认证方式。
详见OAuth官方文档以及RFC5849。
3.2 eYouAutheyouAuth认证方式对于SSO API和Feed API两种接口稍有不同，SSO API传递认证信息是通过HTTP GET的方式，Feed API则是通过把认证信息参数放到HTTP的Authorization头中传递。
3.2.1 SSO API的eYouAuth认证方法：将如下表格中的参数以GET参数的形式传递给SSO API。
注意：由于是通过HTTP GET方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。
参数名参数说明auth_type 认证方式。
为固定的值auth。
auth_key API_KEYauth_timestamp 系统当前的整数时间戳auth_token 会话Token。
此会话T oken需要在调用SSO API之前申请。
申请方法见申请会话Token。
auth_signature 签名。
算法：MD5(API_SECRET + auth_key + auth_timestamp + email + auth_token)email SSO的目标用户的邮件地址。
此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这里列出。
SSO API 的eYouAuth认证完整示例假设如下参数的值为：API_KEY：apitest@API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8Email：test@申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU=系统当前的整数时间戳：1262307600计算签名：MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest@1262307600test@test.eyou.ne tnq54aHpZseNWPwxwfrklZO8uGSU=)计算的结果：fd46a8f76c21e86811d7b22aa60339b1此时得到HTTP GET方式传送所需的五个参数：auth_type : auth ;auth_key : apitest@ ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;对五个参数分别作RawUrlEncode 处理，得到如下结果：auth_type : auth ;auth_key : apitest% ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;那么SSO API的请求URL为：/api/sso/login?auth_type=auth&auth_key=api%&auth_timest amp=1262307600&auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D&email=test@test.eyou .net&auth_signature=fd46a8f76c21e86811d7b22aa60339b13.2.2 Feed API的eYouAuth认证方法：将如下表格中的参数放到HTTP的Authorization头中传递给Feed API。
（Feed API 的eYouAuth认证中，签名的计算不需要email，此处与SSO API不同）注意：由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。