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

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

《API接口调用说明及示例第四次修订.docx》由会员分享，可在线阅读，更多相关《API接口调用说明及示例第四次修订.docx（20页珍藏版）》请在冰豆网上搜索。

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

API接口调用说明及示例（第四次修订）

产品/项目名称Product/ProjectName

保密级别ConfidentialityLevel

eYou邮件系统

机密

产品/项目版本Product/ProjectVersion

最后更新日期LastUpdate

8103

2014-09-12

eYou邮件系统V8接口文档

1API接口简介

API指eYou邮件系统所提供的接口。

调用接口流程图：

为了保证API调用的安全性等因素，eYouMailAPI要求调用方必须持有APIKEY。

此APIKEY需要由调用方向eYouMail方申请此。

eYouMail方在接受调用方申请后，会颁发APIKEY以及一个与之配对的APISECRET。

调用方必须记录此APIKEY以及APISECTET。

APIKEY是API提供方（例如部署了eYou邮件系统的单位）颁发给调用方（例如需要获取eYou邮件系统数据的OA系统）的身份识别串APIKEY。

此APIKEY事一个邮件地址格式的字符串，例如：

apitest@。

API提供方颁发给调用方身份识别串对应的秘钥。

此API_SECRET是一个32字节的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。

API接口分为两大类：

（1）用户提供SSO（单点登录）的SSOAPI。

（2）用于邮件资源操作的FeedAPI。

2API认证概述

为保证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.1OAuth

标准的OAuth认证方式。

详见OAuth官方文档以及RFC5849。

3.2eYouAuth

eyouAuth认证方式对于SSOAPI和FeedAPI两种接口稍有不同，SSOAPI传递认证信息是通过HTTPGET的方式，FeedAPI则是通过把认证信息参数放到HTTP的Authorization头中传递。

3.2.1SSOAPI的eYouAuth认证方法：

将如下表格中的参数以GET参数的形式传递给SSOAPI。

注意：

由于是通过HTTPGET方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。

参数名

参数说明

auth_type

认证方式。

为固定的值auth。

auth_key

API_KEY

auth_timestamp

系统当前的整数时间戳

auth_token

会话Token。

此会话Token需要在调用SSOAPI之前申请。

申请方法见申请会话Token。

auth_signature

签名。

算法：

MD5（API_SECRET+auth_key+auth_timestamp+email+auth_token）

email

SSO的目标用户的邮件地址。

此参数并不是认证信息参数，但是由于在计算签名的时候需要用到，所以这这里列出。

SSOAPI的eYouAuth认证完整示例

假设如下参数的值为：

API_KEY：

apitest@

API_SECRET：

35c51afdb3caa33d1e9b36802c5d79b8

Email：

test@

申请到的会话Token：

nq54aHpZseNWPwxwfrklZO8uGSU=

系统当前的整数时间戳：

1262307600

计算签名：

MD5（35c51afdb3caa33d1e9b36802c5d79b8apitest@1262307600test@nq54aHpZseNWPwxwfrklZO8uGSU=）

计算的结果：

fd46a8f76c21e86811d7b22aa60339b1

此时得到HTTPGET方式传送所需的五个参数：

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;

那么SSOAPI的请求URL为：

3.2.2FeedAPI的eYouAuth认证方法：

将如下表格中的参数放到HTTP的Authorization头中传递给FeedAPI。

（FeedAPI的eYouAuth认证中，签名的计算不需要email，此处与SSOAPI不同）

注意：

由于是通过HTTP头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。

参数名

参数说明

auth_type

认证方式。

为固定的值auth。

auth_key

API_KEY

auth_timestamp

系统当前的整数时间戳

auth_token

会话Token。

此会话Token需要在调用FeedAPI之前申请。

申请方法见申请会话Token。

auth_signature

签名。

算法：

MD5（API_SECRET+auth_key+auth_timestamp+auth_token）

FeedAPI的eYouAuth认证完整示例

假设如下参数的值为：

API_KEY：

apitest@

API_SECRET：

35c51afdb3caa33d1e9b36802c5d79b8

申请到的会话Token：

nq54aHpZseNWPwxwfrklZO8uGSU=

系统当前的整数时间戳：

1262307600

计算签名：

MD5（35c51afdb3caa33d1e9b36802c5d79b8apitest@1262307600nq54aHpZseNWPwxwfrklZO8uGSU=）

计算的结果：

3e7f0e9a79c51f1a67d74ac99fad08a3

此时得到HTTPAuthorization头中传送所需的五个参数：

auth_type:

auth;

auth_key:

apitest@;

auth_timestamp:

1262307600;

auth_token:

nq54aHpZseNWPwxwfrklZO8uGSU=;

auth_signature:

3e7f0e9a79c51f1a67d74ac99fad08a3;

对五个参数分别作RawUrlEncode处理，得到如下结果：

auth_type:

auth;

auth_key:

apitest%;

auth_timestamp:

1262307600;

auth_token:

nq54aHpZseNWPwxwfrklZO8uGSU%3D;

auth_signature:

3e7f0e9a79c51f1a67d74ac99fad08a3;

那么FeedAPI（以获取test@的未读邮件数量为例）的HTTP请求数据包为：

GET/api/user/test%HTTP/1.0

HOST:

Authorization:

authauth_key="api%",

auth_timestamp="1262307600",

auth_token="nq54aHpZseNWPwxwfrklZO8uGSU%3D",

auth_signature="3e7f0e9a79c51f1a67d74ac99fad08a3"

3.2.3申请会话Token：

在eYouAuth认证方式中，SSOAPI和FeedAPI都需要提前申请Token用于传参和计算签名，申请会话Token的请求URL为：

申请会话Token需要向上述URL发送一个content-type为application/x-www-form-urlencoded的HTTPPOST请求，此请求必须包含如下表格中的参数。

注意：

由于是通过HTTP头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。

参数名

参数说明

auth_key

API_KEY

auth_timestamp

系统当前的整数时间戳

auth_signature

签名。

算法：

MD5（API_SECRET+auth_key+auth_timestamp）

email（非必需）

SSO的目标用户的邮件地址。

（SSOAPI时需要此参数，FeedAPI不需要）

上表中的前三个参数必须传递，除了必须传递的参数之外，还可以附加传递其它附加参数，所有的附加参数都会被记录在eYou邮件系统中，以供下一步的验证使用（例如SSOAPI要求必须传递一个email附加参数），但是要注意，附加的参数名不能以auth_开头，以防止和必须传递的参数冲突。

如果申请成功，会话Token将会被放到HTTPPOST请求的应答中输出。

成功或者失败的HTTP应答及说明详见附表1。

获取Token完整示例

假设如下参数的值为：

API_KEY：

apitest@

API_SECRET：

35c51afdb3caa33d1e9b36802c5d79b8

系统当前的整数时间戳：

1262307600

计算签名：

MD5（35c51afdb3caa33d1e9b36802c5d79b8apitest@1262307600）

计算的结果：

36b60aa4fcaf56cd761a9bed78387312

此时得到HTTPPOST所必须的三个参数：

auth_key:

apitest@;

auth_timestamp:

1262307600;

auth_signature:

36b60aa4fcaf56cd761a9bed78387312;

SSOAPI申请Token时需要附加email参数：

email:

test@;

对以上参数分别作RawUrlEncode处理，得到如下结果：

auth_key:

apitest%;

auth_timestamp:

1262307600;

auth_signature:

3e7f0e9a79c51f1a67d74ac99fad08a3;

email:

test%;（SSOAPI申请Token时需要）

那么，FeedAPIHTTPPOST请求数据包为：

POST/api/service/auth/get_token

Host:

Content-Type:

application/x-www-form-urlencoded

Content-Length:

131

auth_key=api%&auth_timestamp=1262307600&auth_signature=36b60aa4fcaf56cd761a9bed78387312

SSOAPIHTTPPOST请求数据包为：

POST/api/service/auth/get_token

Host:

Content-Type:

application/x-www-form-urlencoded

Content-Length:

131

auth_key=api%&auth_timestamp=1262307600&auth_signature=36b60aa4fcaf56cd761a9bed78387312&email=test%

3.3eYouSimpleAuth

eYouSimpleAuth认证方式与eYouAuth认证方式的区别是认证信息参数auth_type为simple，并且不需要申请会话Token。

也就是说，eYouSimpleAuth认证方式就是把eYouAuth认证方式中的auth_type参数变为simple，并且把申请会话Token的步骤去掉，同时把传递的认证参数中涉及会话Token的参数去掉（包括签名中的会话Token）。

对于认证过程来说，除了没有会话Token，其余的处理与eYouAuth一致。

4API接口调用示例

API接口分为SSO单点登陆的SSOAPI和邮件资源操作的FeedAPI。

4.1SSO单点登陆

4.1.1请求URL和方法

GET/SERVER/api/sso/login

4.1.2请求参数及步骤

详见SSOAPI的eYouAuth认证完整示例。

4.2FeedAPI调用

4.2.1资源概述

API以URL资源的形式提供调用。

例如获取test1@这个用户的信件列表的资源地址为：

GET/api/user/test1@

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以用户的增删改查为例，示例各种FeedAPI调用步骤

用户的增删改查

接口名称

请求方式

请求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为用户所在的域。

例如用户的邮件地址为test@，那么USER_NAME为test，DOMAIN_NAME为。

用户Atom部分属性列表

标签（根为atom:

entry）

对应字段

例子

添加

修改

atom:

title

用户账户名

test

√

×

atom:

content

用户真实名

小明

√

√

atom:

updated

创建时间，ATOM格式

2010-04-20T10:

30:

53+08:

00

×

×

eyou:

password

密码

mypassword

√

√

PHP调用用户操作API示例

php

define（'API_KEY','zyy@'）;//定义认证信息API_KEY

define（'API_SECRET','e1fab5ae8163f9649b4f73b6e06c69f7'）;//定义认证信息API_SECRET

define（'SERVER','http:

//172.16.100.128/'）;//定义邮件服务器IP

$auth_timestamp=time（）;//定义当前时间戳

//{{{eYouAuthAPI认证信息

$http=newHttpRequest;

$auth_type='auth';

//申请feedtoken，需要向URL发送一个content-type为application/x-www-form-urlencoded的HTTPPOST请求，此请求必须如下postdata中的三个参数：

$postdata=array（

'auth_key'=>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

//feedAPI认证

//FeedAPI传递认证信息是把认证信息参数放到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'=>