API接口調(diào)用說明及示例(第四次修訂)

1、產(chǎn)品/項(xiàng)目名稱 Product/Project Name保密級別 Confidentiality LeveleYou郵件系統(tǒng)機(jī)密產(chǎn)品/項(xiàng)目版本 Product/Project Version最后更新日期 Last Update81032014-09-12eYou郵件系統(tǒng)V8接口文檔北京億中郵信息技術(shù)有限公司All Rights Reserved 版權(quán)所有 侵權(quán)必究僅供內(nèi)部使用Revision Record 修訂記錄Date日期Revision Version修訂版本Change Description修改描述Author作者2012-11-150.1初稿劉暢2013-10-210.2初稿王永杰

2、2014-04-220.3更新錯誤的md5值傅春花2014-09-120.4重新編輯整理文檔周盈妤目 錄1 API接口簡介42 API認(rèn)證概述52.1 認(rèn)證方式的分類52.2 認(rèn)證方式的選擇62.3 認(rèn)證原理63 認(rèn)證方法詳解及示例63.1 OAuth63.2 eYouAuth63.2.1 SSO API的eYouAuth認(rèn)證方法：63.2.2 Feed API的eYouAuth認(rèn)證方法：83.2.3 申請會話Token：94 API接口調(diào)用示例124.2 Feed API調(diào)用124.2.1 資源概述124.2.2 以用戶的增刪改查為例，示例各種Feed API調(diào)用步驟135 附表171 AP

3、I接口簡介API指eYou郵件系統(tǒng)所提供的接口。調(diào)用接口流程圖：申請 API KEY獲取 API SECRETOAuth認(rèn)證eYouSimpleAuth認(rèn)證eYouAuth認(rèn)證（需要申請token）調(diào)用API接口SSO API Feed API為了保證 API 調(diào)用的安全性等因素，eYouMail API 要求調(diào)用方必須持有 API KEY。此 API KEY 需要由調(diào)用方向 eYouMail 方申請此。 eYouMail 方在接受調(diào)用方申請后，會頒發(fā) API KEY 以及一個與之配對的 API SECRET。調(diào)用方必須記錄此 API KEY 以及 API SECTET。API KEY是API

4、提供方（例如部署了eYou郵件系統(tǒng)的單位）頒發(fā)給調(diào)用方（例如需要獲取eYou郵件系統(tǒng)數(shù)據(jù)的OA系統(tǒng)）的身份識別串API KEY。此API KEY事一個郵件地址格式的字符串，例如：apitest。API提供方頒發(fā)給調(diào)用方身份識別串對應(yīng)的秘鑰。此API_SECRET是一個32字節(jié)的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。 API接口分為兩大類： （1）用戶提供SSO（單點(diǎn)登錄）的SSO API。 （2）用于郵件資源操作的Feed API。2 API認(rèn)證概述為保證API的安全性，防止非法的調(diào)用，識別調(diào)用者身份的合法性，在調(diào)用過程中必須先進(jìn)行API認(rèn)證。 2.1

5、認(rèn)證方式的分類 API支持三種認(rèn)證方式，分別是OAuth、eYouAuth和eYouSimpleAuth方式。OAuth是符合RFC規(guī)范的標(biāo)準(zhǔn)認(rèn)證方式，而eYouAuth和eYouSimpleAuth是eYou自定義的規(guī)范。 2.2 認(rèn)證方式的選擇 由于OAuth認(rèn)證方式比較復(fù)雜，所以不建議使用OAuth認(rèn)證方式，除非您的業(yè)務(wù)必須要求遵循OAuth方式認(rèn)證。eYouAuth比eYouSimpleAuth安全性更高，但是也會更復(fù)雜一些，需要先申請會話Token。如果您對API調(diào)用的安全性要求較高，那么建議您使用eYouAuth認(rèn)證方式。如果您對API調(diào)用的安全性要求不是非常高（比如郵件系統(tǒng)部署在

6、內(nèi)網(wǎng)，只在內(nèi)網(wǎng)使用），那么可以使用eYouSimpleAuth認(rèn)證方式。 2.3 認(rèn)證原理API認(rèn)證的原理是：調(diào)用方在調(diào)用API的同時(shí)需要附加傳遞認(rèn)證信息（API_KEY、API_SECRET、簽名等），API在接收到調(diào)用請求的同時(shí)，首先獲取認(rèn)證信息并進(jìn)行認(rèn)證，如果認(rèn)證失敗則給出錯誤提示，如果認(rèn)證成功則繼續(xù)處理調(diào)用請求，之后返回處理結(jié)果。不同的認(rèn)證方式傳遞的認(rèn)證信息有所不同，有的認(rèn)證方式還需要先獲取一些其他的安全認(rèn)證數(shù)據(jù)用來生成認(rèn)證信息，例如eYouAuth認(rèn)證方式需要先申請會話Token。3 認(rèn)證方法詳解及示例 3.1 OAuth標(biāo)準(zhǔn)的OAuth認(rèn)證方式。詳見 OAuth官方文檔以及RFC5

7、849。 3.2 eYouAutheyouAuth認(rèn)證方式對于SSO API和Feed API兩種接口稍有不同，SSO API傳遞認(rèn)證信息是通過HTTP GET的方式，F(xiàn)eed API則是通過把認(rèn)證信息參數(shù)放到HTTP的Authorization頭中傳遞。 3.2.1 SSO API的eYouAuth認(rèn)證方法：將如下表格中的參數(shù)以GET參數(shù)的形式傳遞給SSO API。注意： 由于是通過HTTP GET方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行RawUrlEncode處理。參數(shù)名參數(shù)說明auth_type認(rèn)證方式。為固定的值auth。auth_keyAPI_KEYauth_timest

8、amp系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳auth_token會話Token。此會話Token需要在調(diào)用SSO API之前申請。申請方法見 申請會話Token。auth_signature簽名。算法：MD5(API_SECRET + auth_key + auth_timestamp + email + auth_token)emailSSO的目標(biāo)用戶的郵件地址。此參數(shù)并不是認(rèn)證信息參數(shù)，但是由于在計(jì)算簽名的時(shí)候需要用到，所以這這里列出。 SSO API 的 eYouAuth認(rèn)證完整示例假設(shè)如下參數(shù)的值為： API_KEY：apitest API_SECRET：35c51afdb3caa33d1e9b3680

9、2c5d79b8 Email：test 申請到的會話Token：nq54aHpZseNWPwxwfrklZO8uGSU=系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳：1262307600計(jì)算簽名：MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest1262307600testnq54aHpZseNWPwxwfrklZO8uGSU=)計(jì)算的結(jié)果：fd46a8f76c21e86811d7b22aa60339b1 此時(shí)得到HTTP GET方式傳送所需的五個參數(shù)：auth_type : auth ;auth_key : apitest ;auth_timestamp : 1262307600

10、 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;對五個參數(shù)分別作RawUrlEncode 處理，得到如下結(jié)果：auth_type : auth ;auth_key : apitest% ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : fd46a8f76c21e86811d7b22aa60339b1 ;那么SSO API

11、的請求URL為： 3.2.2 Feed API的eYouAuth認(rèn)證方法：將如下表格中的參數(shù)放到HTTP的Authorization頭中傳遞給Feed API。（Feed API的eYouAuth認(rèn)證中，簽名的計(jì)算不需要email，此處與SSO API不同）注意： 由于是通過HTTP 頭方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行RawUrlEncode處理。參數(shù)名參數(shù)說明auth_type認(rèn)證方式。為固定的值auth。auth_keyAPI_KEYauth_timestamp系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳auth_token會話Token。此會話Token需要在調(diào)用Feed API之前申請。申

12、請方法見 申請會話Token。auth_signature簽名。算法：MD5(API_SECRET + auth_key + auth_timestamp + auth_token) Feed API 的 eYouAuth認(rèn)證完整示例假設(shè)如下參數(shù)的值為： API_KEY：apitest API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8 申請到的會話Token：nq54aHpZseNWPwxwfrklZO8uGSU=系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳：1262307600計(jì)算簽名：MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest126

13、2307600nq54aHpZseNWPwxwfrklZO8uGSU=)計(jì)算的結(jié)果：3e7f0e9a79c51f1a67d74ac99fad08a3 此時(shí)得到HTTP Authorization頭中傳送所需的五個參數(shù)：auth_type : auth ;auth_key : apitest ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU= ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;對五個參數(shù)分別作RawUrlEncode 處理，得到如下結(jié)果

14、：auth_type : auth ;auth_key : apitest% ;auth_timestamp : 1262307600 ;auth_token : nq54aHpZseNWPwxwfrklZO8uGSU%3D ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;那么Feed API（以獲取test的未讀郵件數(shù)量為例）的HTTP請求數(shù)據(jù)包為：GET /api/user/test% HTTP/1.0HOST: Authorization: auth auth_key="api%", auth_timestamp

15、="1262307600", auth_token="nq54aHpZseNWPwxwfrklZO8uGSU%3D", auth_signature="3e7f0e9a79c51f1a67d74ac99fad08a3" 3.2.3 申請會話Token：在eYouAuth認(rèn)證方式中，SSO API和Feed API都需要提前申請Token用于傳參和計(jì)算簽名，申請會話Token的請求URL為：申請會話Token需要向上述URL發(fā)送一個content-type 為 application/x-www-form-urlencoded 的HTT

16、P POST請求，此請求必須包含如下表格中的參數(shù)。注意： 由于是通過HTTP 頭方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行RawUrlEncode處理。參數(shù)名參數(shù)說明auth_keyAPI_KEYauth_timestamp系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳auth_signature簽名。算法：MD5(API_SECRET + auth_key + auth_timestamp)email (非必需)SSO的目標(biāo)用戶的郵件地址。（SSO API時(shí)需要此參數(shù)，F(xiàn)eed API不需要）上表中的前三個參數(shù)必須傳遞，除了必須傳遞的參數(shù)之外，還可以附加傳遞其它附加參數(shù)，所有的附加參數(shù)都會被記錄在eYou郵

17、件系統(tǒng)中，以供下一步的驗(yàn)證使用（例如SSO API要求必須傳遞一個email附加參數(shù)），但是要注意，附加的參數(shù)名不能以auth_開頭，以防止和必須傳遞的參數(shù)沖突。如果申請成功，會話Token 將會被放到HTTP POST請求的應(yīng)答中輸出。成功或者失敗的 HTTP 應(yīng)答及說明詳見附表1。 獲取Token完整示例假設(shè)如下參數(shù)的值為： API_KEY：apitest API_SECRET：35c51afdb3caa33d1e9b36802c5d79b8系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳：1262307600計(jì)算簽名：MD5(35c51afdb3caa33d1e9b36802c5d79b8apitest126230

18、7600)計(jì)算的結(jié)果：36b60aa4fcaf56cd761a9bed78387312 此時(shí)得到HTTP POST所必須的三個參數(shù)：auth_key : apitest ;auth_timestamp : 1262307600 ;auth_signature : 36b60aa4fcaf56cd761a9bed78387312 ;SSO API申請Token時(shí)需要附加email參數(shù)：email : test ;對以上參數(shù)分別作RawUrlEncode 處理，得到如下結(jié)果：auth_key : apitest% ;auth_timestamp : 1262307600 ;auth_signatu

19、re : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;email : test% ; （SSO API申請Token時(shí)需要）那么，F(xiàn)eed API HTTP POST請求數(shù)據(jù)包為：POST /api/service/auth/get_tokenHost: Content-Type: application/x-www-form-urlencodedContent-Length: 131auth_key=api%&auth_timestamp=1262307600 &auth_signature=36b60aa4fcaf56cd761a9bed783873

20、12 SSO API HTTP POST請求數(shù)據(jù)包為：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認(rèn)證方式與eYouAuth認(rèn)證方式的區(qū)別是認(rèn)證信

21、息參數(shù)auth_type為simple，并且不需要申請會話Token。也就是說，eYouSimpleAuth認(rèn)證方式就是把eYouAuth認(rèn)證方式中的auth_type參數(shù)變?yōu)閟imple，并且把申請會話Token的步驟去掉，同時(shí)把傳遞的認(rèn)證參數(shù)中涉及會話Token的參數(shù)去掉（包括簽名中的會話Token）。對于認(rèn)證過程來說，除了沒有會話Token，其余的處理與eYouAuth一致。4 API接口調(diào)用示例API接口分為SSO單點(diǎn)登陸的SSO API和郵件資源操作的Feed API。 4.1 SSO單點(diǎn)登陸 4.1.1 請求URL和方法 GET /SERVER/api/sso/login 4.1.

22、2 請求參數(shù)及步驟 詳見 SSO API 的 eYouAuth認(rèn)證完整示例。 4.2 Feed API調(diào)用 4.2.1 資源概述API以URL資源的形式提供調(diào)用。例如獲取test1這個用戶的信件列表的資源地址為： GET /api/user/test1Api接口從資源類型來說分為兩大類： 1.資源列表類型，如域列表、用戶列表等； 2.具體的資源詳情類型，如域詳情、用戶詳情等。資源列表類型： Content-Type為application/atom+xml;type=feed這類資源通常支持查詢、分頁，是資源詳情的集合： /atom:feed/opensearch:totalResults：結(jié)

23、果總數(shù) /atom:feed/opensearch:startIndex：開始位置 /atom:feed/opensearch:itemsPerPage：每頁個數(shù) /atom:feed/atom:linkrel="self"：當(dāng)前頁 /atom:feed/atom:linkrel="first"：第一頁 /atom:feed/atom:linkrel="previous"：前一頁 /atom:feed/atom:linkrel="next"：下一頁 /atom:feed/atom:linkrel="las

24、t"：最后一頁 注意：資源列表類型默認(rèn)返回10條數(shù)據(jù)，如需更改，可在請求url后添加參數(shù)控制。 資源列表返回條目控制參數(shù)名參數(shù)作用max-results控制顯示結(jié)果條目的數(shù)量start-index控制返回資源列表的起始條目數(shù)例如：獲取用戶列表接口中，返回100條數(shù)據(jù)：/api/admin/domain/DOMAIN_NAME/user？max-results=100返回從第20條開始的10條數(shù)據(jù)：/api/admin/domain/DOMAIN_NAME/user？start-index=20返回從第20條開始的100條數(shù)據(jù)：/api/admin/domain/DOMAIN_NAME

25、/user？max-results=100&start-index=20資源詳情類型： Content-Type為application/atom+xml;type=entry這類資源有固定標(biāo)簽，這些標(biāo)簽通常都有特殊含義，如： category：目錄、種類； title：標(biāo)題； content：內(nèi)容； summary：摘要。 atom:feed/atom:linkrel="edit"：該資源的編輯地址。 4.2.2 以用戶的增刪改查為例，示例各種Feed API調(diào)用步驟 用戶的增刪改查接口名稱請求方式請求url獲取用戶列表GET/api/admin/doma

26、in/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

27、為 。 用戶Atom部分屬性列表標(biāo)簽（根為atom:entry）對應(yīng)字段例子添加修改atom:title用戶賬戶名test×atom:content用戶真實(shí)名小明atom: updated創(chuàng)建時(shí)間，ATOM格式2010-04-20T10:30:53+08:00××eyou:password密碼mypassword PHP調(diào)用用戶操作API示例<?phpdefine('API_KEY', 'zyy'); / 定義認(rèn)證信息API_KEYdefine('API_SECRET', 'e1fab5ae8163f9

28、649b4f73b6e06c69f7'); / 定義認(rèn)證信息API_SECRETdefine('SERVER', '28/'); / 定義郵件服務(wù)器IP$auth_timestamp = time(); / 定義當(dāng)前時(shí)間戳/ eYouAuth API 認(rèn)證信息$http = new HttpRequest;$auth_type = 'auth'/ 申請feed token， 需要向URL發(fā)送一個content-type 為 application/x-www-form-urlencoded 的HTTP

29、POST請求，此請求必須如下postdata中的三個參數(shù)：$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(HttpRequ

30、est:METH_POST);$http->setPostFields($postdata);$http->setHeaders(array('Content-Type' => 'application/x-www-form-urlencoded');$http->send();$auth_token = $http->getResponseBody(); / 獲取到會話Token/ feed API認(rèn)證 / Feed API傳遞認(rèn)證信息是把認(rèn)證信息參數(shù)放到HTTP的Authorization頭中傳遞。認(rèn)證信息參數(shù)包含auth_ty

31、pe, 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_time

32、stamp' => $auth_timestamp, / 系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳 'auth_token' => $auth_token, / 會話Token 'auth_signature' => $auth_signature, / 簽名 );$tmp = array();foreach($auth_info as $k=>$v) $tmp = $k . '="' . rawurlencode($v) . '"' / 注意：由于是通過HTTP頭方式傳遞認(rèn)證信息參數(shù)，所以所有的參

33、數(shù)的值都必須要進(jìn)行RawUrlEncode處理。$authorization = $auth_type . ' ' . implode(', ', $tmp); / 得到Feed API認(rèn)證 /* 例如$authorization的輸出結(jié)果為： auth auth_key="zyy%", auth_timestamp="1262307600", auth_token="nq54aHpZseNWPwxwfrklZO8uGSU%3D", auth_signature="3e7f0e9a79c51f

34、1a67d74ac99fad08a3"*/ / 添加新用戶 POST方法$title = 'addUser1'$name = 'add user 1'$password = '100100100'$admin_type = 0;$domain_name = ' ' ;$postdata = '<?xml version="1.0" encoding="utf-8"?>' . '<entry xmlns="http:/www.w3.

35、org/2005/Atom" xmlns:eyou=" . '<title>' . $title . '</title>' . '<content>' . $name . '</content>' . '<eyou:password>' . $password . '</eyou:password>' . '<eyou:admin_type>' . $admin_type . &#

36、39;</eyou:admin_type>' . '</entry>'$http->setUrl(SERVER . 'api/admin/domain/' . $domain_name . '/user'); / 根據(jù)接口的請求url設(shè)置$http->setMethod(HttpRequest:METH_POST); / 根據(jù)接口的請求方式設(shè)置請求方法$http->setRawPostData($postdata);$http->setHeaders(array('Authoriza

37、tion' => $authorization); / 在http頭部傳遞認(rèn)證信息$http->send();echo $http->getResponseCode(); / 返回 '200 OK' 代表成功，http應(yīng)答代碼列表參考附表2echo $http->getResponseBody(); / 成功時(shí)返回新用戶xml數(shù)據(jù)，失敗時(shí)提示錯誤原因。/ / 獲取用戶信息 GET方法 （資源詳情類型）$user_name = 'addUser1'$domain_name = ' ' ;$http->setUr

38、l(SERVER . 'api/admin/domain/' . $domain_name . '/user/' . $user_name); / 根據(jù)接口的請求url設(shè)置$http->setMethod(HttpRequest:METH_GET); / 根據(jù)接口的請求方式設(shè)置請求方法$http->setHeaders(array('Authorization' => $authorization, / 在http頭部傳遞認(rèn)證信息'Content-Type' => 'application/atom

39、+xml;type=entry', / 獲取資源詳情類型); $http->send();echo $http->getResponseCode(); / 返回 '200 OK' 代表成功，http應(yīng)答代碼列表參考附表2echo $http->getResponseBody(); / 成功時(shí)返回用戶xml數(shù)據(jù)信息，失敗時(shí)提示錯誤原因。/ / 獲取用戶列表 GET方法 （資源列表類型）$domain_name = ' ' ;$http->setUrl(SERVER . 'api/admin/domain/' . $d

40、omain_name . '/user'); / 根據(jù)接口的請求url設(shè)置$http->setMethod(HttpRequest:METH_GET); / 根據(jù)接口的請求方式設(shè)置請求方法$http->setHeaders(array('Authorization' => $authorization, / 在http頭部傳遞認(rèn)證信息'Content-Type' => 'application/atom+xml;type=feed', / 獲取資源列表類型); $http->send();echo $

41、http->getResponseCode(); / 返回 '200 OK' 代表成功，http應(yīng)答代碼列表參考附表2echo $http->getResponseBody(); / 成功時(shí)返回用戶列表xml數(shù)據(jù)信息，失敗時(shí)提示錯誤原因。/ / 修改用戶信息 UPDATE方法$user_name = ' addUser1' ;$domain_name = ' ' ;$new_content = 'Update User 1' ;$new_quota = 200;$new_admin_type = 1;$putdata = '<?xml version="1.0" encoding="utf-8"?>' . '<entry xmlns="/2005/Atom" xmlns:eyou=" . '<content>' . $new_content . '</content>' . '<eyou:quota>' . $