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

产品 项目名称 Product Project Name保密级别 Confidentiality Level eYou 邮件系统机密 产品 项目版本 Product Project Version最后更新日期 Last Update 81032014 09 12 eYou 邮件系统 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 接口简介 4 2 API 认证概述 5 2 1 认证方式的分类 5 2 2 认证方式的选择 6 2 3 认证原理 6 3 认证方法详解及示例 6 3 1 OAuth 6 3 2 eYouAuth 6 3 2 1 SSO API 的 eYouAuth 认证方法 6 3 2 2 Feed API 的 eYouAuth 认证方法 8 3 2 3 申请会话 Token 9 4 API 接口调用示例 12 4 2 Feed API 调用 12 4 2 1 资源概述 12 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 API 提供方颁发给调用方身份识别串对应的秘钥 此 API SECRET 是一个 32 字节的 字符串 例如 35c51afdb3caa33d1e9b36802c5d79b8 API 接口分为两大类 1 用户提供 SSO 单点登录 的 SSO API 2 用于邮件资源操作的 Feed API 申请 API KEY 获取 API SECRET OAuth 认证eYouAuth 认证 需要申请 token eYouSimpleAuth 认证 调用 API 接口 SSO API 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 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 auth keyAPI KEY auth timestamp 系统当前的整数时间戳 auth token 会话 Token 此会话 Token 需要在调用 SSO API 之前申请 申请方法见 申请会话 Token auth signature 签名 算法 MD5 API SECRET auth key auth timestamp email auth token email SSO 的目标用户的邮件地址 此参数并不是认证信息参数 但是由于在计算签名 的时候需要用到 所以这这里列出 SSO API 的 eYouAuth 认证完整示例 假设如下参数的值为 API KEY apitest API SECRET 35c51afdb3caa33d1e9b36802c5d79b8 Email test 申请到的会话 Token nq54aHpZseNWPwxwfrklZO8uGSU 系统当前的整数时间戳 1262307600 计算签名 MD5 35c51afdb3caa33d1e9b36802c5d79b8apitest 1262307600test test eyou ne tnq54aHpZseNWPwxwfrklZO8uGSU 计算的结果 fd46a8f76c21e86811d7b22aa60339b1 此时得到 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 nq54aHpZseNWPwxwfrklZO8uGSU 3D auth signature fd46a8f76c21e86811d7b22aa60339b1 那么 SSO API 的请求 URL 为 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 那么 Feed API 以获取 test 的未读邮件数量为例 的 HTTP 请求数据包为 GET api user test HTTP 1 0 HOST 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 type 为 application x www form urlencoded 的 HTTP POST 请求 此请求必须包含如下表格中的参数 注意 由于是通过 HTTP 头方式传递认证信息参数 所以所有的参数的值都必须要 进行 RawUrlEncode 处理 参数名参数说明 auth keyAPI KEY auth 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 apitest API SECRET 35c51afdb3caa33d1e9b36802c5d79b8 系统当前的整数时间戳 1262307600 计算签名 MD5 35c51afdb3caa33d1e9b36802c5d79b8apitest 1262307600 计算的结果 36b60aa4fcaf56cd761a9bed78387312 此时得到 HTTP POST 所必须的三个参数 auth key apitest auth timestamp 1262307600 auth signature 36b60aa4fcaf56cd761a9bed78387312 SSO API 申请 Token 时需要附加 email 参数 email test 对以上参数分别作 RawUrlEncode 处理 得到如下结果 auth key apitest auth timestamp 1262307600 auth signature 3e7f0e9a79c51f1a67d74ac99fad08a3 email test SSO API 申请 Token 时需要 那么 Feed API HTTP POST 请求数据包为 POST api service auth get token Host Content Type application x www form urlencoded Content Length 131 auth key api 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 100start index 20 资源详情类型 Content Type 为 application atom xml type entry 这类资源有固定标签 这些标签通常都有特殊含义 如 category 目录 种类 title 标题 content 内容 summary 摘要 atom feed atom link rel edit 该资源的编辑地址 4 2 2 以用户的增删改查为例 示例各种 Feed API 调用步骤 用户的增删改查 接口名称请求方式请求 url 获取用户列表 api admin domain DOMAIN NAME user 获取用户信息 GET 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 示例 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 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 应答代码列表参考附表 2 echo 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 应答代码列表参考附表 2 echo 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 应答代码列表参考附表 2 echo http getResponseBody 成功时返回用户列表 xml 数据信息 失败时提示错误原因 修改用户信息 UPDATE 方法 user name addUser1 domain name new content Update User 1 new quota 200 new admin type 1 putdata new content new quota new admin type http setUrl SERVER api admin