产品/项目名称 Product/Project Name eYou邮件系统 产品/项目版本 Product/Project Version 8103
保密级别 Confidentiality Level 机密 最后更新日期 Last Update 2014-09-12 eYou邮件系统V8接口文档
北京亿中邮信息技术有限公司 All Rights Reserved 版权所有 侵权必究
仅供内部使用
Revision Record 修订记录
Date 日期 2012-11-15 2013-10-21 2014-04-22 2014-09-12
Revision Version 修订版本 0.1 0.2 0.3 0.4 Change Description 修改描述 初稿 初稿 更新错误的md5值 重新编辑整理文档 Author 作者 刘畅 王永杰 傅春花 周盈妤
目 录
1 API接口简介 ------------------------------------------------------------------------ 4 2 API认证概述 ------------------------------------------------------------------------ 5
2.1 认证方式的分类 -------------------------------------------------------------- 5 2.2 认证方式的选择 -------------------------------------------------------------- 5 2.3 认证原理 --------------------------------------------------------------------- 5 3 认证方法详解及示例 ---------------------------------------------------------------- 6
3.1 OAuth ----------------------------------------------------------------------- 6 3.2 eYouAuth -------------------------------------------------------------------- 6
3.2.1 SSO API的eYouAuth认证方法： ------------------------------------- 6 3.2.2 Feed API的eYouAuth认证方法： ------------------------------------ 7 3.2.3 申请会话Token： ------------------------------------------------------ 9
4 API接口调用示例 ------------------------------------------------------------------ 11
4.2 Feed API调用 ---------------------------------------------------------- 11 4.2.1 资源概述 -------------------------------------------------------------- 11 4.2.2 以用户的增删改查为例，示例各种Feed API调用步骤 ---------------- 13
5 附表-------------------------------------------------------------------------------- 17
1 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@test.eyou.net。
API提供方颁发给调用方身份识别串对应的秘钥。此API_SECRET是一个32字节的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。
API接口分为两大类： （1）用户提供SSO（单点登录）的SSO API。 （2）用于邮件资源操作的Feed API。
调用API接口 SSO API Feed API OAuth认证 eYouAuth认证 （需要申请token） 申请 API KEY 获取 API SECRET eYouSimpleAuth认证 2 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 eYouAuth
eyouAuth认证方式对于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_key auth_timestamp 认证方式。为固定的值auth。 API_KEY 系统当前的整数时间戳 会话Token。此会话Token需要在调用SSO API之前申请。 申请方法见 申请会话Token。 签名。 算法：MD5(API_SECRET + auth_key + auth_timestamp + email + auth_token) SSO的目标用户的邮件地址。此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这里列出。 参数说明 auth_token auth_signature email
SSO API 的 eYouAuth认证完整示例
假设如下参数的值为：
API_KEY：apitest@test.eyou.net
API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 Email：test@test.eyou.net
申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU=
系统当前的整数时间戳：1262307600 计算签名：
MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest@test.eyou.net1262307600test@test.eyou.netnq54aHpZseNWPwxwfrklZO8uGSU=)
计算的结果：fd46a8f76c21e86811d7b22aa60339b1
此时得到HTTP GET方式传送所需的五个参数：
auth_type : auth ;
auth_key : apitest@test.eyou.net ; auth_timestamp : 1262307600 ;
auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ; auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;
对五个参数分别作RawUrlEncode 处理，得到如下结果：
auth_type : auth ;
auth_key : apitest%40test.eyou.net ; auth_timestamp : 1262307600 ;
auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ; auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;
那么SSO API的请求URL为：
http://test.eyou.net/api/sso/login?auth_type=auth&auth_key=api%40test.eyou.net&auth_timestamp=1262307600&auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D&email=test@test.eyou.net&auth_signature=fd46a8f76c21e86811d7b22aa60339b1
3.2.2 Feed API的eYouAuth认证方法：
将如下表格中的参数放到HTTP的Authorization头中传递给Feed API。（Feed API的eYouAuth认证中，签名的计算不需要email，此处与SSO API不同）
注意： 由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进
行RawUrlEncode处理。
参数名 auth_type auth_key auth_timestamp 认证方式。为固定的值auth。 API_KEY 系统当前的整数时间戳 会话Token。此会话Token需要在调用Feed API之前申请。 申请方法见 申请会话Token。 签名。 算法：MD5(API_SECRET + auth_key + auth_timestamp + auth_token) 参数说明 auth_token auth_signature
Feed API 的 eYouAuth认证完整示例
假设如下参数的值为：
API_KEY：apitest@test.eyou.net
API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU=
系统当前的整数时间戳：1262307600 计算签名：
MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest@test.eyou.net1262307600nq54aHpZseNWPwxwfrklZO8uGSU=)
计算的结果：3e7f0e9a79c51f1a67d74ac99fad08a3
此时得到HTTP Authorization头中传送所需的五个参数：
auth_type : auth ;
auth_key : apitest@test.eyou.net ; auth_timestamp : 1262307600 ;
auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ; auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;
对五个参数分别作RawUrlEncode 处理，得到如下结果：
auth_type : auth ;
auth_key : apitest%40test.eyou.net ; auth_timestamp : 1262307600 ;
auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ; auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;
那么Feed API（以获取test@test.eyou.net的未读邮件数量为例）的HTTP请求数据包为： GET /api/user/test%40test.eyou.net/mail/-/unread?max-results=1 HTTP/1.0 HOST: test.eyou.net Authorization: auth auth_key=\"api%40test.eyou.net\ auth_timestamp=\"1262307600\ auth_token=\"nq54aHpZseNWPwxwfrklZO8uGSU%3D\ auth_signature=\"3e7f0e9a79c51f1a67d74ac99fad08a3\"
3.2.3 申请会话Token：
在eYouAuth认证方式中，SSO API和Feed API都需要提前申请Token用于传参和计算签名，申请会话Token的请求URL为：
http://test.eyou.net/api/service/auth/get_token
申请会话Token需要向上述URL发送一个content-type 为
application/x-www-form-urlencoded 的HTTP POST请求，此请求必须包含如下表格中的参数。
注意： 由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。
参数名 auth_key auth_timestamp API_KEY 系统当前的整数时间戳 签名。 算法：MD5(API_SECRET + auth_key + auth_timestamp) SSO的目标用户的邮件地址。（SSO API时需要此参数，Feed API不需要） 参数说明 auth_signature email (非必需)
上表中的前三个参数必须传递，除了必须传递的参数之外，还可以附加传递其它附加参数，所有的附加参数都会被记录在eYou邮件系统中，以供下一步的验证使用（例如SSO API要求必须传递一个email附加参数），但是要注意，附加的参数名不能以auth_开头，以防止和必须传递的参数冲突。
如果申请成功，会话Token 将会被放到HTTP POST请求的应答中输出。 成功或者失败的 HTTP 应答及说明详见附表1。
获取Token完整示例
假设如下参数的值为：
API_KEY：apitest@test.eyou.net
API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8
系统当前的整数时间戳：1262307600 计算签名：
MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest@test.eyou.net1262307600) 计算的结果：36b60aa4fcaf56cd761a9bed78387312
此时得到HTTP POST所必须的三个参数：
auth_key : apitest@test.eyou.net ; auth_timestamp : 1262307600 ;
auth_signature : 36b60aa4fcaf56cd761a9bed78387312 ; SSO API申请Token时需要附加email参数：
email : test@test.eyou.net ;
对以上参数分别作RawUrlEncode 处理，得到如下结果：
auth_key : apitest%40test.eyou.net ; auth_timestamp : 1262307600 ;
auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;
email : test%40test.eyou.net ; （SSO API申请Token时需要）
那么，Feed API HTTP POST请求数据包为：
POST /api/service/auth/get_token Host: test.eyou.net
Content-Type: application/x-www-form-urlencoded Content-Length: 131
auth_key=api%40test.eyou.net&auth_timestamp=1262307600 &auth_signature=36b60aa4fcaf56cd761a9bed78387312
SSO API HTTP POST请求数据包为：
POST /api/service/auth/get_token Host: test.eyou.net
Content-Type: application/x-www-form-urlencoded Content-Length: 131
auth_key=api%40test.eyou.net&auth_timestamp=1262307600 &auth_signature=36b60aa4fcaf56cd761a9bed78387312&email=test%40test.eyou.net
3.3 eYouSimpleAuth
eYouSimpleAuth认证方式与eYouAuth认证方式的区别是认证信息参数auth_type为simple，并且不需要申请会话Token。
也就是说，eYouSimpleAuth认证方式就是把eYouAuth认证方式中的auth_type参数变为simple，并且把申请会话Token的步骤去掉，同时把传递的认证参数中涉及会话Token的参数去掉（包括签名中的会话Token）。
对于认证过程来说，除了没有会话Token，其余的处理与eYouAuth一致。
4 API接口调用示例
API接口分为SSO单点登陆的SSO API和邮件资源操作的Feed API。
4.1 SSO单点登陆
4.1.1 请求URL和方法
GET /SERVER/api/sso/login
4.1.2 请求参数及步骤
详见 SSO API 的 eYouAuth认证完整示例。
4.2 Feed API调用
4.2.1 资源概述
API以URL资源的形式提供调用。例如获取test1@test.eyou.net这个用户的信件列表的资源地址为：
GET /api/user/test1@test.eyou.net/mail Api接口从资源类型来说分为两大类： 1.资源列表类型，如域列表、用户列表等； 2.具体的资源详情类型，如域详情、用户详情等。
资源列表类型：
Content-Type为application/atom+xml;type=feed 这类资源通常支持查询、分页，是资源详情的集合： /atom:feed/opensearch:totalResults：结果总数 /atom:feed/opensearch:startIndex：开始位置 /atom:feed/opensearch:itemsPerPage：每页个数 /atom:feed/atom:link[@rel=\"self\"]：当前页 /atom:feed/atom:link[@rel=\"first\"]：第一页 /atom:feed/atom:link[@rel=\"previous\"]：前一页 /atom:feed/atom:link[@rel=\"next\"]：下一页 /atom:feed/atom:link[@rel=\"last\"]：最后一页
注意：资源列表类型默认返回10条数据，如需更改，可在请求url后添加参数控制。 资源列表返回条目控制 参数名 max-results start-index 参数作用 控制显示结果条目的数量 控制返回资源列表的起始条目数 例如：
获取用户列表接口中，返回100条数据：
/api/admin/domain/DOMAIN_NAME/user？max-results=100
返回从第20条开始的10条数据：
/api/admin/domain/DOMAIN_NAME/user？start-index=20
返回从第20条开始的100条数据：
/api/admin/domain/DOMAIN_NAME/user？max-results=100&start-index=20
资源详情类型：
Content-Type为application/atom+xml;type=entry 这类资源有固定标签，这些标签通常都有特殊含义，如： category：目录、种类；
title：标题； content：内容； summary：摘要。
atom:feed/atom:link[@rel=\"edit\"]：该资源的编辑地址。
4.2.2 以用户的增删改查为例，示例各种Feed API调用步骤 用户的增删改查 接口名称 获取用户列表 GET 获取用户信息 添加用户 修改用户信息 删除用户 POST PUT DELETE /api/admin/domain/DOMAIN_NAME/user/USER_NAME /api/admin/domain/DOMAIN_NAME/user /api/admin/domain/DOMAIN_NAME/user/USER_NAME /api/admin/domain/DOMAIN_NAME/user/USER_NAME 请求方式 请求url /api/admin/domain/DOMAIN_NAME/user 说明：
USER_NAME为用户名。
DOMAIN_NAME为用户所在的域。
例如用户的邮件地址为test@test.eyou.net，那么USER_NAME为test ， DOMAIN_NAME 为 test.eyou.net。 用户Atom部分属性列表 标签（根为atom:entry） atom:title atom:content 对应字段 用户账户名 用户真实名 创建时间，ATOM格式 例子 test 小明 2010-04-20T10:30:53+08:00 添加 修改 √ √ × × √ × atom: updated eyou:password 密码 mypassword √ √
PHP调用用户操作API示例 API_KEY, 'auth_timestamp' => $auth_timestamp, 'auth_signature' => md5(API_SECRET . API_KEY . $auth_timestamp), ); $http->setUrl(SERVER . 'api/service/auth/get_token'); $http->setMethod(HttpRequest::METH_POST); $http->setPostFields($postdata); $http->setHeaders(array('Content-Type' => 'application/x-www-form-urlencoded')); $http->send(); $auth_token = $http->getResponseBody(); // 获取到会话Token // feed API认证 // Feed API传递认证信息是把认证信息参数放到HTTP的Authorization头中传递。认证信息参数包含auth_type, auth_key, auth_timestamp, auth_token, auth_signature. 其中auth_signature签名的算法为：MD5(API_SECRET + auth_key + auth_timestamp + auth_token) 。 $auth_signature = md5(API_SECRET . API_KEY . $auth_timestamp . $auth_token); // 获取签名 $auth_info = array( 'auth_key' => API_KEY, // API_KEY 'auth_timestamp' => $auth_timestamp, // 系统当前的整数时间戳 'auth_token' => $auth_token, // 会话Token 'auth_signature' => $auth_signature, // 签名 ); $tmp = array(); foreach($auth_info as $k=>$v){ $tmp[] = $k . '=\"' . rawurlencode($v) . '\"'; // 注意：由于是通过HTTP头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。 }
$authorization = $auth_type . ' ' . implode(', ', $tmp); // 得到Feed API认证 /*
例如$authorization的输出结果为： auth auth_key=\"zyy%40zyy.com\ auth_timestamp=\"1262307600\
auth_token=\"nq54aHpZseNWPwxwfrklZO8uGSU%3D\ auth_signature=\"3e7f0e9a79c51f1a67d74ac99fad08a3\" */ // }}}
// {{{ 添加新用户 POST方法 $title = 'addUser1'; $name = 'add user 1'; $password = '100100100'; $admin_type = 0;
$domain_name = ' test.eyou.net' ;
$postdata = '' . ' ' ' $http->setUrl(SERVER . 'api/admin/domain/' . $domain_name . '/user'); // 根据接口的请求url设置 $http->setMethod(HttpRequest::METH_POST); // 根据接口的请求方式设置请求方法 $http->setRawPostData($postdata); $http->setHeaders(array('Authorization' => $authorization)); // 在http头部传递认证信息 $http->send(); echo $http->getResponseCode(); // 返回 '200 OK' 代表成功，http应答代码列表参考附表2 echo $http->getResponseBody(); // 成功时返回新用户xml数据，失败时提示错误原因。 // }}} // {{{ 获取用户信息 GET方法 （资源详情类型） $user_name = 'addUser1'; $domain_name = ' test.eyou.net' ; xmlns=\"http://www.w3.org/2005/Atom\" $http->setUrl(SERVER . 'api/admin/domain/' . $domain_name . '/user/' . $user_name); // 根据接口的请求url设置 $http->setMethod(HttpRequest::METH_GET); // 根据接口的请求方式设置请求方法 $http->setHeaders(array( 'Authorization' => $authorization, // 在http头部传递认证信息 'Content-Type' => 'application/atom+xml;type=entry', // 获取资源详情类型 )); $http->send(); echo $http->getResponseCode(); // 返回 '200 OK' 代表成功，http应答代码列表参考附表2 echo $http->getResponseBody(); // 成功时返回用户xml数据信息，失败时提示错误原因。 // }}} // {{{ 获取用户列表 GET方法 （资源列表类型） $domain_name = ' test.eyou.net' ; $http->setUrl(SERVER . 'api/admin/domain/' . $domain_name . '/user'); // 根据接口的请求url设置 $http->setMethod(HttpRequest::METH_GET); // 根据接口的请求方式设置请求方法 $http->setHeaders(array( 'Authorization' => $authorization, // 在http头部传递认证信息 'Content-Type' => 'application/atom+xml;type=feed', // 获取资源列表类型 )); $http->send(); echo $http->getResponseCode(); // 返回 '200 OK' 代表成功，http应答代码列表参考附表2 echo $http->getResponseBody(); // 成功时返回用户列表xml数据信息，失败时提示错误原因。 // }}} // {{{ 修改用户信息 UPDATE方法 $user_name = ' addUser1' ; $domain_name = ' test.eyou.net' ; $new_content = 'Update User 1' ; $new_quota = 200; $new_admin_type = 1; $putdata = '' . ' ' xmlns=\"http://www.w3.org/2005/Atom\" ''; $http->setUrl(SERVER . 'api/admin/domain/' . $domain_name . '/user/' . $user_name); // 根据接口的请求url设置 $http->setMethod(HttpRequest::METH_PUT); // 根据接口的请求方式设置请求方法 $http->setHeaders(array('Authorization' => $authorization)); // 在http头部传递认证信息 $http->setPutData($putdata); $http->send(); echo $http->getResponseCode(); // 返回 '200 OK' 代表成功，http应答代码列表参考附表2 echo $http->getResponseBody(); // 成功时返回空，若失败返回错误提示。 // }}} // {{{ 删除组 DELETE 方法 $user_name = 'addUser1'; $domain_name = 'test.eyou.net'; $http->setUrl(SERVER . 'api/admin/domain/' . $domain_name . '/user/' . $user_name); // 根据接口的请求url设置 $http->setMethod(HttpRequest::METH_DELETE); // 根据接口的请求方式设置请求方法 $http->setHeaders(array('Authorization' => $authorization)); // 在http头部传递认证信息 $http->send(); echo $http->getResponseCode(); // 返回 '200 OK' 代表成功，http应答代码列表参考附表2 echo $http->getResponseBody(); // 成功时返回空，若失败返回错误提示。 // }}} ?> 5 附表 附表1： 申请Token时HTTP应答代码说明 返回HTTP代码 200 OK 申请成功 缺少必要的参数。 400 Bad Request 参数格式错误。 说明 参数长度超出限制，必须小于5KB。 401 Unauthorized 500 Internal Server Error 签名验证错误 系统内部错误 附表2： 调用API认证结果的HTTP应答代码说明 返回HTTP代码 200 OK 认证并且API调用成功。 缺少必要的参数。 400 Bad Request 参数格式错误。 参数长度超出限制，必须小于5KB。 401 Unauthorized 500 Internal Server Error 签名验证错误 系统内部错误 说明 因篇幅问题不能全部显示，请点此查看更多更全内容