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

1、API接口调用说明及示例第四次修订API接口调用说明及示例(第四次修订)产品/项目名称 Product/Project Name保密级别 Confidentiality LeveleYou邮件系统机密产品/项目版本 Product/Project Version最后更新日期 Last Update81032014-09-12eYou邮件系统V8接口文档1 API接口简介API指eYou邮件系统所提供的接口。调用接口流程图：为了保证 API 调用的安全性等因素，eYouMail API 要求调用方必须持有 API KEY。此 API KEY 需要由调用方向 eYouMail 方申请此。 eYou

2、Mail 方在接受调用方申请后，会颁发 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（单点登录）的S

3、SO API。 （2）用于邮件资源操作的Feed API。2 API认证概述为保证API的安全性，防止非法的调用，识别调用者身份的合法性，在调用过程中必须先进行API认证。 2.1 认证方式的分类 API支持三种认证方式，分别是OAuth、eYouAuth和eYouSimpleAuth方式。OAuth是符合RFC规范的标准认证方式，而eYouAuth和eYouSimpleAuth是eYou自定义的规范。 2.2 认证方式的选择 由于OAuth认证方式比较复杂，所以不建议使用OAuth认证方式，除非您的业务必须要求遵循OAuth方式认证。eYouAuth比eYouSimpleAuth安全性更高，

4、但是也会更复杂一些，需要先申请会话Token。如果您对API调用的安全性要求较高，那么建议您使用eYouAuth认证方式。如果您对API调用的安全性要求不是非常高（比如邮件系统部署在内网，只在内网使用），那么可以使用eYouSimpleAuth认证方式。 2.3 认证原理API认证的原理是：调用方在调用API的同时需要附加传递认证信息（API_KEY、API_SECRET、签名等），API在接收到调用请求的同时，首先获取认证信息并进行认证，如果认证失败则给出错误提示，如果认证成功则继续处理调用请求，之后返回处理结果。不同的认证方式传递的认证信息有所不同，有的认证方式还需要先获取一些其他的安全认

5、证数据用来生成认证信息，例如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方式传递认证信

6、息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。参数名参数说明auth_type认证方式。为固定的值auth。auth_keyAPI_KEYauth_timestamp系统当前的整数时间戳auth_token会话Token。此会话Token需要在调用SSO API之前申请。申请方法见 申请会话Token。auth_signature签名。算法：MD5(API_SECRET + auth_key + auth_timestamp + email + auth_token)emailSSO的目标用户的邮件地址。此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这

7、里列出。 SSO API 的 eYouAuth认证完整示例 假设如下参数的值为： API_KEY：apitest API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 Email：test 申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU=系统当前的整数时间戳：1262307600计算签名：MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest1262307600testnq54aHpZseNWPwxwfrklZO8uGSU=)计算的结果：fd46a8f76c21e86811d7b22aa60339

8、b1 此时得到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 :

9、nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;那么SSO API的请求URL为： 3.2.2 Feed API的eYouAuth认证方法：将如下表格中的参数放到HTTP的Authorization头中传递给Feed API。（Feed API的eYouAuth认证中，签名的计算不需要email，此处与SSO API不同）注意： 由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。参数名参数说明auth_type认证方式。为固

10、定的值auth。auth_keyAPI_KEYauth_timestamp系统当前的整数时间戳auth_token会话Token。此会话Token需要在调用Feed API之前申请。申请方法见 申请会话Token。auth_signature签名。算法：MD5(API_SECRET + auth_key + auth_timestamp + auth_token) Feed API 的 eYouAuth认证完整示例假设如下参数的值为： API_KEY：apitest API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 申请到的会话Token：nq54aHpZ

11、seNWPwxwfrklZO8uGSU=系统当前的整数时间戳：1262307600计算签名：MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest1262307600nq54aHpZseNWPwxwfrklZO8uGSU=)计算的结果：3e7f0e9a79c51f1a67d74ac99fad08a3 此时得到HTTP Authorization头中传送所需的五个参数：auth_type : auth ;auth_key : apitest ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrk

12、lZO8uGSU= ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;对五个参数分别作RawUrlEncode 处理，得到如下结果：auth_type : auth ;auth_key : apitest% ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;那么Feed API（以获取test的未读邮件数量为例）的HTTP请求数据包为：GET

13、 /api/user/test% HTTP/1.0HOST: Authorization: auth auth_key=api%, auth_timestamp=1262307600, auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D, auth_signature=3e7f0e9a79c51f1a67d74ac99fad08a3 3.2.3 申请会话Token：在eYouAuth认证方式中，SSO API和Feed API都需要提前申请Token用于传参和计算签名，申请会话Token的请求URL为：申请会话Token需要向上述URL发送一个content-t

14、ype 为 application/x-www-form-urlencoded 的HTTP POST请求，此请求必须包含如下表格中的参数。注意： 由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。参数名参数说明auth_keyAPI_KEYauth_timestamp系统当前的整数时间戳auth_signature签名。算法：MD5(API_SECRET + auth_key + auth_timestamp)email (非必需)SSO的目标用户的邮件地址。（SSO API时需要此参数，Feed API不需要）上表中的前三个参数必须传递，

15、除了必须传递的参数之外，还可以附加传递其它附加参数，所有的附加参数都会被记录在eYou邮件系统中，以供下一步的验证使用（例如SSO API要求必须传递一个email附加参数），但是要注意，附加的参数名不能以auth_开头，以防止和必须传递的参数冲突。如果申请成功，会话Token 将会被放到HTTP POST请求的应答中输出。成功或者失败的 HTTP 应答及说明详见附表1。 获取Token完整示例假设如下参数的值为： API_KEY：apitest API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8系统当前的整数时间戳：1262307600计算签名：MD5(3

16、5c51afdb3caa33d1e9b36802c5d79b8apitest1262307600)计算的结果：36b60aa4fcaf56cd761a9bed78387312 此时得到HTTP POST所必须的三个参数：auth_key : apitest ;auth_timestamp : 1262307600 ;auth_signature : 36b60aa4fcaf56cd761a9bed78387312 ;SSO API申请Token时需要附加email参数：email : test ;对以上参数分别作RawUrlEncode 处理，得到如下结果：auth_key : apitest

17、% ;auth_timestamp : 1262307600 ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;email : test% ; （SSO API申请Token时需要）那么，Feed API HTTP POST请求数据包为：POST /api/service/auth/get_tokenHost: Content-Type: application/x-www-form-urlencodedContent-Length: 131auth_key=api%&auth_timestamp=1262307600 &auth_sign

18、ature=36b60aa4fcaf56cd761a9bed78387312 SSO API HTTP POST请求数据包为：POST /api/service/auth/get_tokenHost: Content-Type: application/x-www-form-urlencodedContent-Length: 131auth_key=api%&auth_timestamp=1262307600 &auth_signature=36b60aa4fcaf56cd761a9bed78387312&email=test% 3.3 eYouSimpleAutheYouSimpleAuth

19、认证方式与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 /S

20、ERVER/api/sso/login 4.1.2 请求参数及步骤 详见 SSO API 的 eYouAuth认证完整示例。 4.2 Feed API调用 4.2.1 资源概述API以URL资源的形式提供调用。例如获取test1这个用户的信件列表的资源地址为： GET /api/user/test1Api接口从资源类型来说分为两大类： 1.资源列表类型，如域列表、用户列表等； 2.具体的资源详情类型，如域详情、用户详情等。资源列表类型： Content-Type为application/atom+xml;type=feed这类资源通常支持查询、分页，是资源详情的集合： /atom:feed/o

21、pensearch:totalResults：结果总数 /atom:feed/opensearch:startIndex：开始位置 /atom:feed/opensearch:itemsPerPage：每页个数 /atom:feed/atom:linkrel=self：当前页 /atom:feed/atom:linkrel=first：第一页 /atom:feed/atom:linkrel=previous：前一页 /atom:feed/atom:linkrel=next：下一页 /atom:feed/atom:linkrel=last：最后一页 注意：资源列表类型默认返回10条数据，如需更改

22、，可在请求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-inde

23、x=20资源详情类型： Content-Type为application/atom+xml;type=entry这类资源有固定标签，这些标签通常都有特殊含义，如： category：目录、种类； title：标题； content：内容； summary：摘要。 atom:feed/atom:linkrel=edit：该资源的编辑地址。 4.2.2 以用户的增删改查为例，示例各种Feed API调用步骤 用户的增删改查接口名称请求方式请求url获取用户列表GET/api/admin/domain/DOMAIN_NAME/user获取用户信息/api/admin/domain/DOMAIN_NA

24、ME/user/USER_NAME添加用户POST/api/admin/domain/DOMAIN_NAME/user修改用户信息PUT/api/admin/domain/DOMAIN_NAME/user/USER_NAME删除用户DELETE/api/admin/domain/DOMAIN_NAME/user/USER_NAME说明：USER_NAME为用户名。DOMAIN_NAME为用户所在的域。例如用户的邮件地址为test，那么USER_NAME为test ， DOMAIN_NAME 为 。 用户Atom部分属性列表标签（根为atom:entry）对应字段例子添加修改atom:title

25、用户账户名testatom:content用户真实名小明atom: updated创建时间，ATOM格式2010-04-20T10:30:53+08:00eyou: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(HttpReque

26、st: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 =