API接口調用說明及示例(第四次修訂)解讀

1、產品屈目名稱 Product/Project Name保密級別 Confidentiality LeveleYou郵件系統(tǒng)機密產品/項目版本 Product/Project Version最后更新日期Last Update81032014-09-12eYou郵件系統(tǒng)V8接口文檔II億由B北京億中郵信息技術有限公司All Rights Reserved版權所有 侵權必究僅供內部使用Revision Record 修訂記錄DateRevision VersionChange DescriptionAuthor日期修訂版本修改描述作者2012-11-150.1初稿劉暢2013-10-210.2初稿王

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

3、72 API認證概述API指eYou郵件系統(tǒng)所提供的接口。 調用接口流程圖：為了保證API調用的安全性等因素，eYouMail API要求調用方必須持有API KEY。此API KEY需要由調用方向eYouMail方申請此。eYouMail方在接受調用方申請后，會頒發(fā)API KEY以及一個與之配對的API SECREL調用方必須記錄此API KEY以及API SECTET0API KEY是API提供方（例如部署了 eYou郵件系統(tǒng)的單位）頒發(fā)給調用方（例如需要 獲取eYou郵件系統(tǒng)數(shù)據的0A系統(tǒng)）的身份識別串API KEY。此API KEY事一個郵件地址 格式的字符串，例如：apitestoA

4、PI提供方頒發(fā)給調用方身份識別串對應的秘鑰。此API_SECRET是一個32字節(jié)的字 符串，例如 35c51afdb3caa33dle9b36802c5d79b8oAPI接口分為兩大類：（工）用戶提供SSO （單點登錄）的SSO API0（2 ）用于郵件資源操作的Feed API0為保證API的安全性，防止非法的調用，識別調用者身份的合法性，在調用過程中必 須先進行API認證。2.1 認證方式的分類API支持三種認證方式，分別是OAuth、eYouAuth和eYouSimpleAuth方式。 OAuth是符合RFC規(guī)范的標準認證方式，而eYouAuth和eYouSimpleAuth是eYou自

5、 定義的規(guī)范。2.2 認證方式的選擇由于OAuth認證方式比較復雜，所以不建議使用OAuth認證方式，除非您的業(yè)務必 須要求遵循OAuth方式認證。eYouAuth比eYouSimpleAuth安全性更高，但是也會更復雜一些，需要先申請會話 Token。如果您對API調用的安全性要求較高，那么建議您使用eYouAuth認證方式。如果 您對API調用的安全性要求不是非常高（比如郵件系統(tǒng)部署在內網，只在內網使用），那 么可以使用eYouSimpleAuth認證方式。2.3 認證原理API認證的原理是：調用方在調用API的同時需要附加傳遞認證信息（APLKEY、 APLSECRET、簽名等），API

6、在接收到調用請求的同時，首播取認證信息并進行認證， 如果認證失敗則給出錯誤提示，如果認證成功則繼續(xù)處理調用請求，之后返回處理結果。不同的認證方式傳遞的認證信息有所不同，有的認證方式還需要先交取一些其他的安全 認證數(shù)據用來生成認證信息，例如eYouAuth認證方式需要先申請會話Token。3認證方法詳解及示例3.1 OAuth標準的OAuth認證方式。詳見OAuth官方文檔以及RFC5849。3.2 eYouAutheyouAuth認證方式對于SSO API和Feed API兩種接口稍有不同，SSO API傳遞認 證信息是通過HTTP GET的方式，F(xiàn)eed API則是通過把認證信息參數(shù)放到HT

7、TP的 Authorization 頭中傳遞。3.2.1 SSO API 的 eYouAuth 認證方法：將如下表格中的參數(shù)以GET參數(shù)的形式傳遞給SSO API0注意：由于是通過HTTP GET方式傳遞認證信息參數(shù)，所以所有的般的值都必須要 進行 RawUrlEncode 處理。參數(shù)名參數(shù)說明auth-type認證方式.為固定的值auth。auth-keyAPI.KEYauthjimestamp系統(tǒng)當前的整數(shù)時間戳authjoken會話Token.此會話Token需要在調用SSO API之前申請。申請方法見申請會話Token.auth.signature算法：MD5(API_SECRET +

8、 auth.key + authjimestamp + email + authjoken)emailSSO的目標用戶的郵件地址。此參數(shù)并不是認證信息參數(shù)，但是由于在計算簽名的時候需要用到，所以這這里列出.SSO API的eYouAuth認證完整示例假設如下參數(shù)的值為：API_KEY : apitestAPLSECRET : 35c51afdb3caa33dle9b36802c5d79b8Email : test申請到的會話 Token : nq54aHpZseNWPwxwfrklZO8uGSU=系統(tǒng)當前的整數(shù)時間戳：1262307600計算簽名：MD5(35c51afdb3caa33dle9

9、b36802c5d79b8apitestl262307600testtest.eyou.ne tnq54aHpZseNWPwxwfrklZO8uGSU=)計算的結果：fd46a8f76c21e86811d7b22aa60339bl此際尋到HTTP GET方式彳專送所需的五個參數(shù):auth-type:auth;auth-key:apitest;authjimestamp : 1262307600;authjoken:nq54aHpZseNWPwxwfrklZO8uGSU=;auth_signature :fd46a8f76c21e86811d7b22aa60339bl;對五個參數(shù)分別作RawUr

10、lEncode處理，得到如下結果：auth.type:auth;auth-key:apitest%;authjimestamp : 1262307600;authjoken:nq54aHpZseNWPwxwfrklZO8uGSU%3D;auth_signature :fd46a8f76c21e86811d7b22aa60339bl;那么SSO API的請求URL為： amp=1262307600&authJoken=nq54aHpZseNWPwxwfrklZ08uGSU%3D&email=testtest.eyou .net&auth_signature=fd46a8f

11、76c21e86811d7b22aa60339bl3.2.2 Feed API 的 eYouAuth 認證方法：將如下表格中的參數(shù)放到HTTP的Authorization頭中傳遞給Feed API。（ Feed API 的eYouAuth認證中，簽名的計算不需要email ,此處與SSO API不同）注意：由于是通過HTTP頭方式傳遞認證信息參數(shù),所以所有的參數(shù)的值都必須要進行 RawUrlEncode 處理。參數(shù)名參數(shù)說明auth-type認證方式.為固定的值auth。auth_keyAPLKEYauthjimestamp系統(tǒng)當前的整數(shù)時間戳會話Token。此會話Token需要在調用Feed

12、 API之前申請.authjoken申請方法見申請會話Token。auth.signature算法：MD5(APLSECRET + auth.key + authjimestamp + authjoken)Feed API的eYouAuth認證完整示例假設如下參數(shù)的值為：APLKEY : apitestAPLSECRET : 35c51afdb3caa33dle9b36802c5d79b8申請到的會話 Token : nq54aHpZseNWPwxwfrklZO8uGSU=系統(tǒng)當前的整數(shù)時間戳：1262307600計算簽名:MD5(35c51afdb3caa33dle9b36802c5d79b

13、8apitest(S)l262307600nq54aHpZseNWP wxwfrklZO8uGSU=)計算的結果:3e7f0e9a79c51fla67d74ac99fad08a3此時得到HTTP Authorization頭中傳送所需的五個參數(shù)：auth-type:auth;auth.key:apitest;authjimestamp : 1262307600;authjoken:nq54aHpZseNWPwxwfrklZO8uGSU=;auth.signature :3e7f0e9a79c51fla67d74ac99fad08a3;對五個參數(shù)分別作RawUrlEncode處理，得到如下結果：

14、auth.type:auth;auth-key:apitest%;authjimestamp : 1262307600;authjoken:nq54aHpZseNWPwxwfrklZO8uGSU%3D;auth_signature :3e7f0e9a79c51fla67d74ac99fad08a3;那么Feed API （以獲取test的未讀郵件數(shù)量為例）的HTTP請求數(shù)據包為：GET /api/user/test% HTTP/1.0HOST: Authorization: auth auth.key="api%'authJimestamp=w1262307600authJo

15、ken=-nq54aHpZseNWPwxwfrklZO8uGSU%3D-/ auth_signature=-3e7f0e9a79c51fla67d74ac99fad08a3"3.2.3 申請會話Token :在eYouAuth認證方式中，SSO API和Feed API都需要提前申請Token用于傳參和 計算簽名，申請會話Token的請求URL為：申請會話Token需要向上述URL發(fā)送一個content-type為 application/x-www-form-urlencoded的HTTP POST請求，此請求必須包含如下表格 中的參數(shù)。注意：由于是通過HTTP頭方式傳遞認證信息參

16、數(shù),所以所有的參數(shù)的值都必須要進 行 RawUrlEncode 處理。參數(shù)名參數(shù)說明auth-keyAPI_KEYauthjimestamp系統(tǒng)當前的整數(shù)時間戳auth.signature算法：MD5（API_SECRET + auth.key + authjimestamp）email （非必需）SSO的目標用戶的郵件地址。（SSO API時需要此參數(shù)，F(xiàn)eed API不需要）上表中的前三個參數(shù)必須傳遞，除了必須傳遞的參數(shù)之外，還可以附加傳遞其它附加參 數(shù)，所有的附加參數(shù)都會被記錄在eYou郵件系統(tǒng)中以供下一步的驗證使用（例如SSO API 要求必須傳遞一個email附加參數(shù)），但是要注意，

17、附加的參數(shù)名不能以auth_開頭，以防 止和必須傳遞的參數(shù)沖突。如果申請成功，會話Token將會被放到HTTP POST請求的應答中輸出。 成功或者失敗的HTTP應答及說明詳見附表1。獲取Token完整示例假設如下參數(shù)的值為：APLKEY : apitestAPLSECRET : 35c51afdb3caa33dle9b36802c5d79b8系統(tǒng)當前的整數(shù)時間戳：1262307600計算簽名：MD5(35c51afdb3caa33dle9b36802c5d79b8apitestl262307600) 計算的結果:36b60aa4fcaf56cd761a9bed78387312此時得到HTTP

18、 POST所必須的三個參數(shù)：auth.key : apitest;authjimestamp : 1262307600;auth.signature : 36b60aa4fcaf56cd761a9bed78387312;SSO API申請Token時需要附加email參數(shù)： email:test;對以上參數(shù)分別作RawUrlEncode處理，得到如下結果：auth.key:apitest%;authjimestamp:1262307600;auth_signature:3e7f0e9a79c51fla67d74ac99fad08a3;email:test%; ( SSOAPI申i青 Token

19、 時需要)那么,Feed API HTTP POST請求數(shù)據包為：POST /api/service/auth/getjokenHost: Content-Type: application/x-www-form-urlencodedContent-Length: 131auth-key=api%&auth_timestamp=1262307600 &auth-signature=36b60aa4fcaf56cd761a9bed78387312SSO API HTTP POST請求數(shù)據包為：POST /api/service/auth/getjokenHost: Content

20、-Type: application/x-www-form-urlencodedContent-Length: 131auth-key=api%&auth_timestamp=1262307600&auth-signature=36b60aa4fcaf56cd761a9bed78387312&email=test%3.3 eYouSimpleAutheYouSimpleAuth認證方式與eYouAuth認證方式的區(qū)別是認證信息參數(shù)auth_type 為simple ,并且不需要申請會話Token。也就是說，eYouSimpleAuth認證方式就是把eYouAuth認證方

21、式中的auth_type參 數(shù)變?yōu)閜imple ,并且把申請會話Token的步驟去掉,同時把傳遞的認證參數(shù)中涉及會話 Token的參數(shù)去掉（包括簽名中的會話Token ）。對于認證過程來說，除了沒有會話Token ,其余的處理與eYouAuth 一致。4 API接口調用示例API接口分為SSO單點登陸的SSO API和郵件資源操作的Feed API。4.1 SSO單點登陸4.1.1 請求URL和方法GET /SERVER/api/sso/login4.1.2 請求參數(shù)及步驟詳見SSO API的eYouAuth認證完整示例。4.2 Feed API 調用4.2.1 資源概述API以URL資源的形

22、式提供調用。例如獲取testl這個用戶的信件列 表的資源地址為：GET /api/user/testlApi接口從資源類型來說分為兩大類：L資源列表類型，如域列表、用戶列表等；2.具體的資源詳情類型，如域詳情、用戶詳情等。資源列表類型：Content-Type 為 application/atom+xml;type=feed 這類資源通常支持查詢、分頁，是資源詳情的集合：/atom:feed/opensearch:totalResults :結果總數(shù)/atom:feed/opensearch:startlndex :開始位置/atom:feed/opensearch:itemsPerPage

23、:每頁個數(shù)/atom:feed/atom:linkrel="self":當前頁/atom:feed/atom:linkrel="first":第一頁/atom:feed/atom:link（§）rel = "previous":前一頁/atom:feed/atom:linkrel=',nextM:下一頁/atom:feed/atom:linkrel="last":最后一頁注意：資源列表類型默認返回10條數(shù)據，如需更改，可在請求url后添加參數(shù)控制。資源列表返回條目控制參數(shù)名max-results參

24、數(shù)作用控制顯示結果條目的數(shù)量start-index控制返回資源列表的起始條目數(shù)例如：獲取用戶列表接口中，返回100條數(shù)據:/api/admin/domain/DOMAIN_NAME/user ? max-results=100 返回從第20條開始的10條數(shù)據:/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 為 applicat

25、ion/atom+xml;type=entry 這類資源有固定標簽，這些標簽通常都有特殊含義，如：category :目錄、種類;title :標題;content:內容;summary :摘要。atom:feed/atom:linkrel="edit":該資源的編輯地址。422以用戶的增刪改查為例，示例各種Feed API調用步驟用戶的增刪改查接口名稱請求方式請求url獲取用戶列表GET/api/admin/domain/DOMAIN_NAME/user獲取用戶信息/api/admin/domain/DOMAIN_NAME/user/USER_NAME添加用戶POST/a

26、pi/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_N AM E 為 test , DOMAIN_NAME 為 test.eyou.neU用戶Atom部分屬性列表標簽（根為atom:entry ）對應字段例子添加修改atomititle用戶賬戶名test

27、VXatomxontent用戶真實名小明VVatom: updated創(chuàng)建時間,ATOM格式2010-04-20710:30:53+08:00XXeyou:password密碼mypasswordVVPHP調用用戶操作API示例<?phpdefineCAPLKEY； 'zyy,)；/ 定義認證信息 API KEYdefineCAPLSECRET； ,elfab5ae8163f9649b4f73b6e06c69f7,); / 定義認四任Tdefine(SERVER/http:L28/');/ 定義郵件服務器 IP$authjimestamp = tim

28、e();/ 定義當前時間戳/ eYouAuth API 認iiH言息$http = new HttpRequest;$auth_type = 'auth'/ 申請 feed token,需要向 URL 發(fā)送一個 content-type 為 application/x-www-form-urlencoded 的HTTP POST請求,此請求必須如下postdata中的三個參數(shù)： $postdata = array(,auth.key' => API.KEY,'authjimestamp* = > $authjimestampf,auth.signat

29、ure* => md5(API_SECRET . API_KEY . $authjimestamp)f);$http->setUrl(SERVER. 'api/service/auth/getjoken*);$http->setMethod(HttpRequest:METH_POST);$http->setPostFields($postdata);$http->setHeaders(array('Content-Type' => pplication/x-www-form-urlencoded*);$http->send();

30、$authjoken = $http->getResponseBody();/ 獲取到會話 Token/ feed API 認證/ Feed API傳遞認證信息是把認證信息參數(shù)放到HTTP的Authorization頭中傳遞。認證信息參數(shù)包 含 authjype, auth_keyf authjimestamp, authjoken, auth_signature. 其中 authsignature 的算法為:MD5(APLSECRET + auth.key + authjimestamp + authjoken)。$auth.signature = md5(APLSECRET . AP

31、I_KEY . $auth_timestamp . Sauthjoken); / 獲取簽名$authjnfo = array(/ APLKEY/系統(tǒng)當前的整數(shù)時間戳/ 會話 Token/簽名/汪荽：由于是通過HTTP頭方式傳,auth.key' => APLKEY, 'authjimestamp* => $authjimestampf 'authjoken' = > $authjokenr ,auth.signature* => $auth_signaturef );$tmp = arrayO;foreach($authjnfo as $

32、k=>$v)$tmp = $k. *=*. rawurlencode($v).遞認證信息參數(shù),所以所有的參數(shù)的值都必須要進行RawUrlEncode處理。)$authorization = $auth_type . * *. implode('r $tmp); 得到 Feed API 認證/*例如$authorization的輸出結果為：auth auth-key="zyy%auth_timestamp="1262307600,authJoken=Mnq54aHpZseNWPwxwfrklZO8uGSU%3D；auth.signature=M3e7f0e9a7

33、9c51fla67d74ac99fad08a3"*/ /添加新用戶POST方法$title = 'addllserl,;$name = 'add user 1,;$password = '100100100,;$admin_type = 0;$ = * "$postdata = '<?xml version=*1.0" encoding="utf-8"?>'.'(entryxmlns=w/2005/AtomMxmlns:eyou=&

34、quot;'<content>>. $name . '</content>>.'<eyou:password>*. $password . '</eyou:password>*.'<eyou:admin_type>' $adminjype . ,</eyou:adminjype>>.'/entry,'；$http->setllrl(SERVER . 'api/admin/domain/* . $domain_name . 

35、9;/user'); / 根據按口的請求 url 設置$http->setMethod(HttpRequest:METH_POST);/ 根據接口的請求方式設置請求方法$http->setRawPostData($postdata);$http- >setHeaders(arrayCAuthorization' = > $authorization); / 在 http 頭臺陽專遞認證信息 $http->send();echo $http->getResponseCodeO； /返回200 OK,代表成功f http應答代碼列表參考附表2 e

36、cho $http->getResponseBodyO； /成功時返回新用戶xml數(shù)據，失敗時提示錯謖原因. /獲取用戶信息GET方法(斐源詳情類型)$user_name = 'addUserl"$ = * *;$http->setllrl(SERVER . pi/admin/domain/*. $domain_name ,'/user/'. S); / 根據 接口的請求url設置$http->setMethod(HttpRequest:METH.GET);/ 根據接口的請求方式設置請求方法$http-

37、>setHeaders(array(,Authorization' => $authorization,/ 在 http 頭部傳遞認證信息'Content-Type' => ,application/atom+xml;type=entry'r / 獲取資源詳情類型 );$http->send();echo $http->getResponseCode(); / 返回 200 OK，代表硼 f http 應U表參考附表 2 echo $http->getResponseBodyO； / 皿時返回用戶xml數(shù)4息，翔因. /獲取用

38、戶列表GET方法(奧源列表類型)$ = 1 *;$http->setllrl(SERVER . pi/admin/domain/* . $domain-name '/user'); 眼據接口的請求 url 設置$http->setMethod(HttpRequest:METH.GET);/ 根據接口的請求方式設置請求方法$http->setHeaders(array('Authorization' => $authorization,/ 在 http 頭部傳遞認證信息,Content-Type' =>

39、*application/atom+xml;type=feed; / 荻取資源列表);$http->send();echo $http->getResponseCodeO； / 返回 200 OK'代表硼 f http 應投搦表參考附表 2 echo $http->getResponseBodyO； /成功時返回用戶列表xml數(shù)據信息，失敗時提示錯誤原因. /修改用戶信息UPDATE方法$ = * addUserl'$ = 1 "Snew-content = *Update User 1,;$new.quota = 200;$new.adminjype = 1;$putdata = ,<?xml version=*11.0" encoding=Mutf-8M?>'.entryxmlns= "http: /2005/Atom”xmlns:eyou=*'(content'. $new_content. *</content>*.'<eyou:quota>>. $new_quota