API接口调用说明及示例第四次修订.docx
- 文档编号:24837257
- 上传时间:2023-06-02
- 格式:DOCX
- 页数:15
- 大小:73.68KB
API接口调用说明及示例第四次修订.docx
《API接口调用说明及示例第四次修订.docx》由会员分享,可在线阅读,更多相关《API接口调用说明及示例第四次修订.docx(15页珍藏版)》请在冰豆网上搜索。
API接口调用说明及示例第四次修订
产品/项目名称Product/ProjectName
保密级别ConfidentialityLevel
eYou邮件系统
机密
产品/项目版本Product/ProjectVersion
最后更新日期LastUpdate
8103
2014-09-12
eYou邮件系统V8接口文档
北京亿中邮信息技术有限公司
AllRightsReserved版权所有XX
仅供内部使用
RevisionRecord修订记录
Date
日期
RevisionVersion
修订版本
ChangeDescription
修改描述
Author
作者
2012-11-15
初稿
刘畅
2013-10-21
初稿
王永杰
2014-04-22
更新错误的md5值
傅春花
2014-09-12
重新编辑整理文档
周盈妤
1API接口简介
API指eYou邮件系统所提供的接口。
调用接口流程图:
为了保证API调用的安全性等因素,eYouMailAPI要求调用方必须持有APIKEY。
此APIKEY需要由调用方向eYouMail方申请此。
eYouMail方在接受调用方申请后,会颁发APIKEY以及一个与之配对的APISECRET。
调用方必须记录此APIKEY以及APISECTET。
APIKEY是API提供方(例如部署了eYou邮件系统的单位)颁发给调用方(例如需要获取eYou邮件系统数据的OA系统)的身份识别串APIKEY。
此APIKEY事一个邮件地址格式的字符串,例如。
API提供方颁发给调用方身份识别串对应的秘钥。
此API_SECRET是一个32字节的字符串,例如35c51afdb3caa33d1e9b36802c5d79b8。
API接口分为两大类:
(1)用户提供SSO(单点登录)的SSOAPI。
(2)用于邮件资源操作的FeedAPI。
2API认证概述
为保证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官方文档以及RFC5849。
eYouAuth
eyouAuth认证方式对于SSOAPI和FeedAPI两种接口稍有不同,SSOAPI传递认证信息是通过HTTPGET的方式,FeedAPI则是通过把认证信息参数放到HTTP的Authorization头中传递。
SSOAPI的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)
SSO的目标用户的邮件地址。
此参数并不是认证信息参数,但是由于在计算签名的时候需要用到,所以这这里列出。
SSOAPI的eYouAuth认证完整示例
假设如下参数的值为:
API_KEY
API_SECRET:
35c51afdb3caa33d1e9b36802c5d79b8
申请到的会话Token:
nq54aHpZseNWPwxwfrklZO8uGSU=
系统当前的整数时间戳:
00
计算签名=)
计算的结果:
fd46a8f76c21e86811d7b22aa60339b1
此时得到HTTPGET方式传送所需的五个参数:
auth_type:
auth;
auth_key;
auth_timestamp:
00;
auth_token:
nq54aHpZseNWPwxwfrklZO8uGSU=;
auth_signature:
fd46a8f76c21e86811d7b22aa60339b1;
对五个参数分别作RawUrlEncode处理,得到如下结果:
auth_type:
auth;
auth_key:
apitest%;
auth_timestamp:
00;
auth_token:
nq54aHpZseNWPwxwfrklZO8uGSU%3D;
auth_signature:
fd46a8f76c21e86811d7b22aa60339b1;
那么SSOAPI的请求URL为:
&auth_key=api%&auth_timestamp=00&auth_token=nq54aHpZseNWPwxwfrklZO8uGSU%3D&&auth_signature=fd46a8f76c21e86811d7b22aa60339b1
FeedAPI的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
API_SECRET:
35c51afdb3caa33d1e9b36802c5d79b8
申请到的会话Token:
nq54aHpZseNWPwxwfrklZO8uGSU=
系统当前的整数时间戳:
00
计算签名=)
计算的结果:
3e7f0e9a79c51f1a67d74ac99fad08a3
此时得到HTTPAuthorization头中传送所需的五个参数:
auth_type:
auth;
auth_key;
auth_timestamp:
00;
auth_token:
nq54aHpZseNWPwxwfrklZO8uGSU=;
auth_signature:
3e7f0e9a79c51f1a67d74ac99fad08a3;
对五个参数分别作RawUrlEncode处理,得到如下结果:
auth_type:
auth;
auth_key:
apitest%;
auth_timestamp:
00;
auth_token:
nq54aHpZseNWPwxwfrklZO8uGSU%3D;
auth_signature:
3e7f0e9a79c51f1a67d74ac99fad08a3;
那么FeedAPI(以获取的未读邮件数量为例)的HTTP请求数据包为:
GET/api/user/test%HTTP/
HOST:
authauth_key="api%",
auth_timestamp="00",
auth_token="nq54aHpZseNWPwxwfrklZO8uGSU%3D",
auth_signature="3e7f0e9a79c51f1a67d74ac99fad08a3"
申请会话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
API_SECRET:
35c51afdb3caa33d1e9b36802c5d79b8
系统当前的整数时间戳:
00
计算签名)
计算的结果:
36b60aa4fcaf56cd761a9bed
此时得到HTTPPOST所必须的三个参数:
auth_key;
auth_timestamp:
00;
auth_signature:
36b60aa4fcaf56cd761a9bed;
SSOAPI申请Token时需要附加email参数:
email;
对以上参数分别作RawUrlEncode处理,得到如下结果:
auth_key:
apitest%;
auth_timestamp:
00;
auth_signature:
3e7f0e9a79c51f1a67d74ac99fad08a3;
email:
test%;(SSOAPI申请Token时需要)
那么,FeedAPIHTTPPOST请求数据包为:
POST/api/service/auth/get_token
Host:
application/x-www-form-urlencoded
Content-Length:
131
auth_key=api%&auth_timestamp=00&auth_signature=36b60aa4fcaf56cd761a9bed
SSOAPIHTTPPOST请求数据包为:
POST/api/service/auth/get_token
Host:
application/x-www-form-urlencoded
Content-Length:
131
auth_key=api%&auth_timestamp=00&auth_signature=36b60aa4fcaf56cd761a9bed&email=test%
eYouSimpleAuth
eYouSimpleAuth认证方式与eYouAuth认证方式的区别是认证信息参数auth_type为simple,并且不需要申请会话Token。
也就是说,eYouSimpleAuth认证方式就是把eYouAuth认证方式中的auth_type参数变为simple,并且把申请会话Token的步骤去掉,同时把传递的认证参数中涉及会话Token的参数去掉(包括签名中的会话Token)。
对于认证过程来说,除了没有会话Token,其余的处理与eYouAuth一致。
4API接口调用示例
API接口分为SSO单点登陆的SSOAPI和邮件资源操作的FeedAPI。
SSO单点登陆
请求URL和方法
GET/SERVER/api/sso/login
请求参数及步骤
详见SSOAPI的eYouAuth认证完整示例。
FeedAPI调用
资源概述
API以URL资源的形式提供调用。
例如获取这个用户的信件列表的资源地址为:
GET/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/usermax-results=100
返回从第20条开始的10条数据:
/api/admin/domain/DOMAIN_NAME/userstart-index=20
返回从第20条开始的100条数据:
/api/admin/domain/DOMAIN_NAME/usermax-results=100&start-index=20
资源详情类型:
Content-Type为application/atom+xml;type=entry
这类资源有固定标签,这些标签通常都有特殊含义,如:
category:
目录、种类;
title:
标题;
content:
内容;
summary:
摘要。
atom:
feed/atom:
link[@rel="edit"]:
该资源的编辑地址。
以用户的增删改查为例,示例各种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为用户所在的域。
例如用户的邮件地址为,那么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示例
define('API_KEY','');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();其中auth_signature签名的算法为: MD5(API_SECRET+auth_key+auth_timestamp+auth_token)。 $auth_signature=md5(API_SECRET.API_KEY.$auth_timestamp.$auth_token);'="'.rawurlencode($v).'"';''.implode(',',$tmp);' eyou="">'. ' ' ' password>'.$password.' password>'. ' admin_type>'.$admin_type.' admin_type>'. ''; $http->setUrl(SERVER.'api/admin/domain/'.$domain_name.'/user');'api/admin/domain/'.$domain_name.'/user/'.$user_name);'api/admin/domain/'.$domain_name.'/user');' eyou="">'. ' ' quota>'.$new_quota.' quota>'. ' admin_type>'.$new_admin_type.' admin_type>'. ''; $http->setUrl(SERVER.'api/admin/domain/'.$domain_name.'/user/'.$user_name);'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();//返回'200OK'代表成功,http应答代码列表参考附表2 echo$http->getResponseBody();//成功时返回空,若失败返回错误提示。 //}}} > 5附表 附表1: 申请Token时HTTP应答代码说明 返回HTTP代码 说明 200OK 申请成功 400BadRequest 缺少必要的参数。 参数格式错误。 参数长度超出限制,必须小于5KB。 401Unauthorized 签名验证错误 500InternalServerError 系统内部错误 附表2: 调用API认证结果的HTTP应答代码说明 返回HTTP代码 说明 200OK 认证并且API调用成功。 400BadRequest 缺少必要的参数。 参数格式错误。 参数长度超出限制,必须小于5KB。 401Unauthorized 签名验证错误 500InternalServerError 系统内部错误
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- API 接口 调用 说明 示例 第四 修订