产品/项目名称Product/Project Name 保密级别Co nfide ntiality Level eYou邮件系统机密产品/ 项目版本Product/Project Versio n 最后更新日期Last Update8103 2014-09-12 eYou邮件系统V8接口文档北京亿中邮信息技术有限公司All Rights Reserved版权所有侵权必究仅供内部使用Revision Record 修订记录1 API接口简介------------------------------------------------------------------------ 32 API认证概述------------------------------------------------------------------------ 4认证方式的分类------------------------------------------------------------------ 4认证方式的选择------------------------------------------------------------- 5 认证原理------------------------------------------------------------------------ 5 3 认证方法详解及示例 ----------------------------------------------------------------- 5OAuth -------------------------------------------------------------------------------------------------------------- 5 eYouAuth --------------------------------------------------------------------------------------------------------- 5 SSO API的eYouAuth 认证方法：------------------------------------------- 5Feed API 的eYouAuth 认证方法：------------------------------------------- 7申请会话Token： -------------------------------------------------------------------------------------- 8 4 API接口调用示例-------------------------------------------------------------- 10Feed API 调用 --------------------------------------------------------- 10资源概述 -------------------------------------------------------------- 10以用户的增删改查为例，示例各种Feed API调用步骤--------------------- 11 5 附表 -------------------------------------------------------------------------- 131 API接口简介API指eYou邮件系统所提供的接口。
调用接口流程图：申请API KEY获取API SECRET调用API接口SSO API Feed API为了保证API调用的安全性等因素，eYouMail API要求调用方必须持有API KEY此API KEY需要由调用方向eYouMail方申请此。
eYouMail方在接受调用方申请后，会颁发API KEY以及一个与之配对的API SECRET调用方必须记录此API KEY以及API SECTE。
API KEY是API提供方（例如部署了eYou邮件系统的单位）颁发给调用方（例如需要获取eYou邮件系统数据的OA系统）的身份识别串API KEY此API KEY事一个邮件地址格式的字符串，例如。
API提供方颁发给调用方身份识别串对应的秘钥。
此API_SECRE是一个32字节的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。
API接口分为两大类：（1 ）用户提供SSO（单点登录）的SSO AP J（2）用于邮件资源操作的Feed API。
2 API认证概述为保证API的安全性，防止非法的调用，识别调用者身份的合法性，在调用过程中必须先进行API认证。
认证方式的分类API支持三种认证方式，分别是OAuth、eYouAuth和eYouSimpleAuth方式。
OAuth是符合RFC规范的标准认证方式，而eYouAuth和eYouSimpleAuth是eYou自定义的规范。
认证方式的选择由于OAuth认证方式比较复杂，所以不建议使用OAuth认证方式，除非您的业务必须要求遵循OAuth方式认证。
eYouAuth比eYouSimpleAuth安全性更高，但是也会更复杂一些，需要先申请会话Token。
如果您对API调用的安全性要求较高，那么建议您使用eYouAuth认证方式。
如果您对API调用的安全性要求不是非常高（比如邮件系统部署在内网，只在内网使用），那么可以使用eYouSimpleAuth 认证方式。
认证原理API认证的原理是：调用方在调用API的同时需要附加传递认证信息（API_KEY API_SECRET 签名等），API在接收到调用请求的同时，首先获取认证信息并进行认证，如果认证失败则给出错误提示，如果认证成功则继续处理调用请求，之后返回处理结果。
不同的认证方式传递的认证信息有所不同，有的认证方式还需要先获取一些其他的安全认证数据用来生成认证信息，例如eYouAuth认证方式需要先申请会话Token。
3认证方法详解及示例OAuth标准的OAuth认证方式。
详见OAuth官方文档以及RFC584QeY ouAutheyouAuth认证方式对于SSO AP和Feed API两种接口稍有不同，SSO AP传递认证信息是通过HTTP GET的方式，Feed API则是通过把认证信息参数放到HTTP的Authorization头中传递。
SSO AP的eYouAuth认证方法:将如下表格中的参数以GET参数的形式传递给SSO API注意：由于是通过HTTP GET方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode 处理。
参数名参数说明auth_type 认证方式。
为固定的值auth。
auth_key API_KEYauth_timestamp 系统当前的整数时间戳auth_token会话Token。
此会话Token需要在调用SSO AP之前申请。
申请方法见申请会话Token。
auth_signature签名。
算法：MD5(API_SECRET + auth_key + auth_timestamp + email + auth_token)emailSSO的目标用户的邮件地址。
此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这里列岀。
SSO API的eYouAuth认证完整示例假设如下参数的值为：API_KEYAPI_SECRE:T 35c51afdb3caa33d1e9b36802c5d79b8Email申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU= 系统当前的整数时间戳：00计算签名=)计算的结果：fd46a8f76c21e86811d7b22aa60339b1此时得到HTTP GET方式传送所需的五个参数：auth_typeauth_key ;auth ;auth_timestamp auth_token :00 ;nq54aHpZseNWPwxwfrklZO8uGSU=;auth_signature :fd46a8f76c21e86811d7b22aa60339b1 ; 对五个参数分别作RawUrlEncode处理，得到如下结果: auth_typeauth_keyauth ; apitest% ;auth_timestamp auth_token :00 ;:nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature :fd46a8f76c21e86811d7b22aa60339b1 ;那么SSO AP的请求URL为：& auth_key=api%&auth_timestamp=OO&auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D&&auth_signature=fd46a8f76c21e86811d7b22aa60339b1Feed API的eYouAuth 认证方法:将如下表格中的参数放到HTTP的Authorization头中传递给Feed AP b（Feed API的eYouAuth认证中，签名的计算不需要email，此处与SSO API不同）注意：由于是通过HTTP头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode 处理。
参数名参数说明auth_type 认证方式。
为固定的值auth。
auth_key API_KEYauth_timestamp 系统当前的整数时间戳会话Token。
此会话Token需要在调用Feed API之前申请。
auth_token - 申请方法见申请会话Token。
签名。
auth_signature算法：MD5(API_SECRET + auth_key + auth_timestamp + auth_token)Feed API的eYouAuth认证完整示例假设如下参数的值为：API_KEYAPI_SECRE:T 35c51afdb3caa33d1e9b36802c5d79b8 申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU= 系统当前的整数时间戳：00计算签名=)计算的结果：3e7f0e9a79c51f1a67d74ac99fad08a3此时得到HTTP Authorization头中传送所需的五个参数：auth_type : auth ;auth_key ;auth_timestamp : 00 ;nq54aHpZseNWPwxwfrklZO8uGSU=; 3e7f0e9a79c51f1a67d74ac99fad08a3 ;nq54aHpZseNWPwxwfrklZO8uGSU%3D ; auth_signature :3e7f0e9a79c51f1a67d74ac99fad08a3 ;那么Feed API （以获取的未读邮件数量为例）的 HTTP 请求数据包为: GET /api/user/test% HTTP/ HOST: auth auth_key="api%",auth_timestamp="00", auth_token="nq54aHpZseNWPwxwfrklZO8uGSU%3D", auth_signature="3e7f0e9a79c51f1a67d74ac99fad08a3"申请会话Token ：在eYouAuth 认证方式中，SSO AP 和Feed API 都需要提前申请 Token 用于传参和计算签 名，申请会话Token 的请求URL 为：申请会话Token 需要向上述 URL 发送一个content-type 为 application/x-www-form-urlencoded 的HTTP POST 请求，此请求必须包含如下表格中的参数。