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

产品/项目名称 Product/Project Name保密级别 Confidentiality LeveleYou邮件系统机密产品/项目版本 Product/Project Version最后更新日期 Last Update81032014-09-12eYou邮件系统V8接口文档北京亿中邮信息技术有限公司All Rights Reserved 版权所有 侵权必究仅供内部使用Revision Record 修订记录Date日期Revision Version修订版本Change Description修改描述Author作者2012-11-150.1初稿刘畅2013-10-210.2初稿王永杰2014-04-220.3更新错误的md5值傅春花2014-09-120.4重新编辑整理文档周盈妤目 录1 API接口简介42 API认证概述52.1 认证方式的分类52.2 认证方式的选择62.3 认证原理63 认证方法详解及示例63.1 OAuth63.2 eYouAuth63.2.1 SSO API的eYouAuth认证方法：63.2.2 Feed API的eYouAuth认证方法：83.2.3 申请会话Token：94 API接口调用示例124.2 Feed API调用124.2.1 资源概述124.2.2 以用户的增删改查为例，示例各种Feed API调用步骤135 附表171 API接口简介API指eYou邮件系统所提供的接口。调用接口流程图：申请 API KEY获取 API SECRETOAuth认证eYouSimpleAuth认证eYouAuth认证（需要申请token）调用API接口SSO API Feed API为了保证 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事一个邮件地址格式的字符串，例如：。API提供方颁发给调用方身份识别串对应的秘钥。此API_SECRET是一个32字节的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。 API接口分为两大类： （1）用户提供SSO（单点登录）的SSO 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安全性更高，但是也会更复杂一些，需要先申请会话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_keyAPI_KEYauth_timestamp系统当前的整数时间戳auth_token会话Token。此会话Token需要在调用SSO API之前申请。申请方法见 申请会话Token。auth_signature签名。算法：MD5(API_SECRET + auth_key + auth_timestamp + email + auth_token)emailSSO的目标用户的邮件地址。此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这里列出。 SSO API 的 eYouAuth认证完整示例假设如下参数的值为： API_KEY： API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 Email： 申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU=系统当前的整数时间戳：1262307600计算签名：MD5(35nq54aHpZseNWPwxwfrklZO8uGSU=)计算的结果：fd46a8f76c21e86811d7b22aa60339b1 此时得到HTTP GET方式传送所需的五个参数：auth_type : auth ;auth_key : ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;对五个参数分别作RawUrlEncode 处理，得到如下结果：auth_type : auth ;auth_key : apitest%40 ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;那么SSO API的请求URL为：/api/sso/login?auth_type=auth&auth_key=api%40&auth_timestamp=1262307600&auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D&email=&auth_signature=fd46a8f76c21e86811d7b22aa60339b1 3.2.2 Feed API的eYouAuth认证方法：将如下表格中的参数放到HTTP的Authorization头中传递给Feed API。（Feed API的eYouAuth认证中，签名的计算不需要email，此处与SSO API不同）注意： 由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。参数名参数说明auth_type认证方式。为固定的值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： API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 申请到的会话Token：nq54aHpZseNWPwxwfrklZO8uGSU=系统当前的整数时间戳：1262307600计算签名：MD5(351262307600nq54aHpZseNWPwxwfrklZO8uGSU=)计算的结果：3e7f0e9a79c51f1a67d74ac99fad08a3 此时得到HTTP Authorization头中传送所需的五个参数：auth_type : auth ;auth_key : ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;对五个参数分别作RawUrlEncode 处理，得到如下结果：auth_type : auth ;auth_key : apitest%40 ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;那么Feed API（以获取的未读邮件数量为例）的HTTP请求数据包为：GET /api/user/test%40/mail/-/unread?max-results=1 HTTP/1.0HOST: Authorization: auth auth_key=api%40, auth_timestamp=1262307600, auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D, auth_signature=3e7f0e9a79c51f1a67d74ac99fad08a3 3.2.3 申请会话Token：在eYouAuth认证方式中，SSO API和Feed API都需要提前申请Token用于传参和计算签名，申请会话Token的请求URL为：/api/service/auth/get_token申请会话Token需要向上述URL发送一个content-type 为 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不需要）上表中的前三个参数必须传递，除了必须传递的参数之外，还可以附加传递其它附加参数，所有的附加参数都会被记录在eYou邮件系统中，以供下一步的验证使用（例如SSO API要求必须传递一个email附加参数），但是要注意，附加的参数名不能以auth_开头，以防止和必须传递的参数冲突。如果申请成功，会话Token 将会被放到HTTP POST请求的应答中输出。成功或者失败的 HTTP 应答及说明详见附表1。 获取Token完整示例假设如下参数的值为： API_KEY： API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8系统当前的整数时间戳：1262307600计算签名：MD5(351262307600)计算的结果：36b60aa4fcaf56cd761a9bed78387312 此时得到HTTP POST所必须的三个参数：auth_key : ;auth_timestamp : 1262307600 ;auth_signature : 36b60aa4fcaf56cd761a9bed78387312 ;SSO API申请Token时需要附加email参数：email : ;对以上参数分别作RawUrlEncode 处理，得到如下结果：auth_key : apitest%40 ;auth_timestamp : 1262307600 ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;email : test%40 ; （SSO API申请Token时需要）那么，Feed API HTTP POST请求数据包为：POST /api/service/auth/get_tokenHost: Content-Type: application/x-www-form-urlencodedContent-Length: 131auth_key=api%40&auth_timestamp=1262307600 &auth_signature=36b60aa4fcaf56cd761a9bed78387312 SSO API HTTP POST请求数据包为：POST /api/service/auth/get_tokenHost: Content-Type: application/x-www-form-urlencodedContent-Length: 131auth_key=api%40&auth_timestamp=1262307600 &auth_signature=36b60aa4fcaf56cd761a9bed78387312&email=test%40 3.3 eYouSimpleAutheYouSimpleAuth认证方式与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资源的形式提供调用。例如获取这个用户的信件列表的资源地址为： GET /api/user//mailApi接口从资源类型来说分为两大类： 1.资源列表类型，如域列表、用户列表等； 2.具体的资源详情类型，如域详情、用户详情等。资源列表类型： Content-Type为application/atom+xml;type=feed这类资源通常支持查询、分页，是资源详情的集合： /atom:feed/opensearch: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条数据，如需更改，可在请求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:linkrel=edit：该资源的编辑地址。 4.2.2 以用户的增删改查为例，示例各种Feed API调用步骤 用户的增删改查接口名称请求方式请求url获取用户列表GET/api/admin/domain/DOMAIN_NAME/user获取用户信息/api/admin/domain/DOMAIN_NAME/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为用户所在的域。例如用户的邮件地址为，那么USER_NAME为test ， DOMAIN_NAME 为 。 用户Atom部分属性列表标签（根为atom:entry）对应字段例子添加修改atom:title用户账户名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(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%40, auth_timestamp=1262307600, auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D, auth_signature=3e7f0e9a79c51f1a67d74ac99fad08a3*/ / 添加新用户 POST方法$title = addUser1;$name = add user 1;$password = 100100100;$admin_type = 0;$domain_name = ;$postdata = . . . $title . . . $name . . . $password . . . $admin_type . . ;$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应答代码列表参考附表2echo $http-getResponseBody(); / 成功时返回新用户xml数据，失败时提示错误原因。/ / 获取用户信息 GET方法 （资源详情类型）$user_name = addUser1;$domain_name = ;$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应答代码列表参考附表2echo $http-getResponseBody(); / 成功时返回用户xml数据信息，失败时提示错误原因。/ / 获取用户列表 GET方法 （资源列表类型）$domain_name = ;$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应答代码列表参考附表2echo $http-getResponseBody(); / 成功时返回用户列表xml数据信息，失败时提示错误原因。/ / 修改用户信息 UPDATE方法$user_name = addUser1 ;$do