API接口調用說明及示例第四次修訂

1、產品 /項目名稱 Product/Project Name保密級別 Co nfide ntiality LeveleYou郵件系統(tǒng)機密產品 / 項目版本 P roduct/ Project Version最后更新日期Last Up date81032014-09-12eYou郵件系統(tǒng)V8接口文檔UfZ 郵北京億中郵信息技術有限公司All Rights Reserved版權所有 侵權必究僅供內部使用Revision Record 修訂記錄DateRevisi on Versio nChange Descri pti onAuthor日期修訂版本修改描述作者2012-11-15初稿劉暢2013-1

2、0-21初稿王永杰更新錯誤的md5值傅春花2014-04-222014-09-12重新編輯整理文檔周盈妤API接口簡介API認證概述認證方式的分類認證方式的選擇認證原理認證方法詳解及示例OAutheYouAuthSSO API的eYouAuth認證方法:Feed API 的 eYouAuth 認證方法:申請會話Token：API接口調用示例Feed API 調用資源概述以用戶的增刪改查為例，示例各種Feed API調用步驟10101011附表13API接口簡介API指eYou郵件系統(tǒng)所提供的接口。 調用接口流程圖：申請API KEY 獲取 API SECRET1OAuth認證eYouAuth

3、認證（需要申請token）eYouSimpleAuth 認證調用API接口SSO APIFeed API為了保證 API調用的安全性等因素，eYouMail API要求調用方必須持有 API KEY此 API KEY需要由調用方向 eYouMail方申請此。eYouMail方在接受調用方申請后，會頒發(fā)API KEY以及一個與之配對的API SECRET調用方必須記錄此 API KEY以及 API SECTEJAPI KEY是 API提供方（例如部署了 eYou郵件系統(tǒng)的單位）頒發(fā)給調用方（例如需要獲 取eYou郵件系統(tǒng)數(shù)據(jù)的 OA系統(tǒng)）的身份識別串API KEY此API KEY事一個郵件地址格

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

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

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

7、TTP的Authorization頭中傳遞。SSO AP的eYouAuth認證方法:將如下表格中的參數(shù)以 GET參數(shù)的形式傳遞給 SSO API注意：由于是通過HTT P GET方式傳遞認證信息參數(shù)，所以所有的參數(shù)的值都必須要進 行 RawUrlEncode 處理。參數(shù)名參數(shù)說明auth_t ype認證方式。為固定的值auth。auth_keyAPI KEYauth_timesta mp系統(tǒng)當前的整數(shù)時間戳會話Token。此會話Token需要在調用SSO AP之前申請。auth token申請方法見申請會話Token。簽名。auth_signature算法：MD5(A PI_SECRET +

8、auth_key + auth_timesta mp + email + auth_token)SSO的目標用戶的郵件地址。此參數(shù)并不是認證信息參數(shù)，但是由于在計算簽名的email時候需要用到，所以這這里列出。SSO API 的eYouAuth認證完整示例假設如下參數(shù)的值為:API KEYAPI SECRET 35c51afdb3caa33d1e9b36802c5d79b8Email申請到的會話 Token： nq54aHpZseNWPwxwfrklZO8uGSU=系統(tǒng)當前的整數(shù)時間戳：00計算簽名=)計算的結果：fd46a8f76c21e86811d7b22aa60339b1此時得到HTTP

9、 GET方式傳送所需的五個參數(shù):auth_t ypeauth ;auth_key ;auth_timesta mpauth token00 ;nq54a Hp ZseNWPwxwfrklZO8uGSU=;auth_signaturefd46a8f76c21e86811d7b22aa60339b1 ;對五個參數(shù)分別作RawUrlEncode處理，得到如下結果:auth_t ypeauth ;auth_keyap itest% ;auth_timesta mp:nq54a Hp ZseNWPwxwfrklZO8uGSU%3D ;auth token:00 ;auth_signaturefd46a8

10、f76c21e86811d7b22aa60339b1 ;auth_t ype認證方式。為固定的值auth。auth_keyAPI KEYauth_timesta mp系統(tǒng)當前的整數(shù)時間戳那么SSO AP的請求URL為:& auth_key=a pi%&auth_timesta mp=00&auth_token=nq54aH pZseNWPwxwfrklZO8uGSU%3D&&auth_signature=fd46a8f76c21e86811d7b22aa60339b1Feed API的 eYouAuth 認證方法:將如下表格中的參數(shù)放到HTTP的Auth

11、orization頭中傳遞給 Feed APL（ Feed API的eYouAuth認證中，簽名的計算不需要email，此處與SSO AP不同）注意：由于是通過_HTTP_頭方式傳遞認證信息參數(shù)，所以所有的參數(shù)的值都必須要進 行 RawUrlEncode 處理。參數(shù)名參數(shù)說明會話Token。此會話Token需要在調用Feed API之前申請。auth token申請方法見申請會話Token。簽名。auth_signature算法：MD5(A PI_SECRET + auth_key + auth_timesta mp + auth_token)Feed API 的eYouAuth認證完整示例假

12、設如下參數(shù)的值為:API KEYAPI SECRET 35c51afdb3caa33d1e9b36802c5d79b8申請到的會話 Token： nq54aHpZseNWPwxwfrklZO8uGSU=系統(tǒng)當前的整數(shù)時間戳：00 計算簽名=)計算的結果：3e7f0e9a79c51f1a67d74ac99fad08a3此時得到HTTP Authorization頭中傳送所需的五個參數(shù):auth ;auth_t ypeauth_key ;auth_timesta mp: 00 ;auth tokennq54a Hp ZseNWPwxwfrklZO8uGSU=;auth_signature :3e7

13、f0e9a79c51f1a67d74ac99fad08a3 ;對五個參數(shù)分別作RawUrlEncode處理，得到如下結果:auth_t ype auth_keyauth ;ap itest% ;auth_timesta mp:00 ;auth tokenauth_signature:nq54a Hp ZseNWPwxwfrklZO8uGSU%3D ;:3e7f0e9a79c51f1a67d74ac99fad08a3 ;那么Feed API （以獲取的未讀郵件數(shù)量為例）的HTTP請求數(shù)據(jù)包為:GET /ap i/user/test% HTT P/HOST: auth auth_key="

14、;api%".auth_timesta mp=" 00",auth_token="nq54aH pZseNWPwxwfrklZO8uGSU%3D",auth_signature="3e7f0e9a79c51f1a67d74ac99fad08a3"申請會話Token：在eYouAuth認證方式中，SSO AP和Feed API都需要提前申請 Token用于傳參和計算簽 名，申請會話Token的請求URL為：申請會話Token需要向上述 URL發(fā)送一個content-type 為application/x-www-form-ur

15、lencoded的HTTP POST請求，此請求必須包含如下表格中的參數(shù)。注意：由于是通過HTTP頭方式傳遞認證信息參數(shù)，所以所有的參數(shù)的值都必須要進 行 RawUrlEncode.處理。參數(shù)名參數(shù)說明auth_keyAPI KEYauth_timesta mp系統(tǒng)當前的整數(shù)時間戳簽名。auth_signature算法：MD5(A PI_SECRET + auth_key + auth_timesta mp)email (非必需)SSO的目標用戶的郵件地址。（SSO AP時需要此參數(shù)，F(xiàn)eed API不需要）上表中的前三個參數(shù)必須傳遞，除了必須傳遞的參數(shù)之外，還可以附加傳遞其它附加參數(shù)，所有的

16、附加參數(shù)都會被記錄在eYou郵件系統(tǒng)中，以供下一步的驗證使用（例如 SSO API要求必須傳遞一個 email附加參數(shù)），但是要注意，附加的參數(shù)名不能以auth_開頭，以防止和必須傳遞的參數(shù)沖突。如果申請成功，會話 Toke n將會被放到HTT P POST青求的應答中輸出。 成功或者失敗的 HTT P應答及說明詳見附表1。獲取Token完整示例假設如下參數(shù)的值為:API KEYAP l_SECRE:T 35c51afdb3caa33d1e9b36802c5d79b8系統(tǒng)當前的整數(shù)時間戳：00 計算簽名）計算的結果：36b60aa4fcaf56cd761a9bed此時得到HTTPPOST所必須

17、的三個參數(shù):auth_key ;auth_timesta mp: 00 ;36b60aa4fcaf56cd761a9bed ;auth_signatureSSO API申請Token時需要附加email參數(shù):email ;對以上參數(shù)分別作 RawUrlEncode處理，得到如下結果:auth_keyap itest% ;auth_timesta mp:00 ;auth_signatureemail:3e7f0e9a79c51f1a67d74ac99fad08a3 ;:test% ;（SSO API申請 Token 時需要） 那么，F(xiàn)eed API HTTP POST#求數(shù)據(jù)包為:POST /a

18、p i/service/auth/get_tokenHost: app lication/x-www-form-urlencodedContent-Length: 131auth_key=a pi%&auth_timestam p=00 & auth_signature=36b60aa4fcaf56cd761a9bedSSO API HTTP POST請求數(shù)據(jù)包為:POST /ap i/service/auth/get_tokenHost: app lication/x-www-form-urlencodedContent-Length: 131auth_key=a pi%&a

19、mp;auth_timestam p=00 & auth_signature=36b60aa4fcaf56cd761a9bed&email=test%eYouSim pl eAutheYouSimpleAuth認證方式與eYouAuth認證方式的區(qū)別是認證信息參數(shù)auth_type為simple,并且不需要申請會話Token。也就是說，eYouSimpleAuth 認證方式就是把 eYouAuth 認證方式中的 auth_type 參數(shù)變?yōu)?simple,并且把申請會話 Token的步驟去掉，同時把傳遞的認證參數(shù)中涉及會話Token的參數(shù)去掉（包括簽名中的會話 Token）。對

20、于認證過程來說，除了沒有會話Token,其余的處理與 eYouAuth 一致。4 API接口調用示例API接口分為SSC單點登陸的SSO AP和郵件資源操作的 Feed AP。SSO單點登陸請求URL和方法GET /SERVER/a pi/sso/logi n請求參數(shù)及步驟詳見SSO API的eYouAuth認證完整示例。Feed API 調用資源概述API以URL資源的形式提供調用。例如獲取這個用戶的信件列表的資源地址為:GET/mailApi接口從資源類型來說分為兩大類：1. 資源列表類型，如域列表、用戶列表等；2. 具體的資源詳情類型，如域詳情、用戶詳情等。資源列表類型：Content-

21、Type 為 application/atom+xml;type=feed 這類資源通常支持查詢、分頁，是資源詳情的集合：/atomfeed/opensearch:totalResults :結果總數(shù) /atomfeed/opensearch:startIndex :開始位置 /atomfeed/opensearch:itemsPerPage :每頁個數(shù) /atom:feed/atom:li nkrel="self":當前頁 /atom:feed/atom:li nkrel="first":第一頁 /atom:feed/atom:li nkrel=&qu

22、ot; previous":前一頁/atom:feed/atom:li nkrel=" next":下一頁/atom:feed/atom:li nkrel="last":最后一頁注意：資源列表類型默認返回10條數(shù)據(jù)，如需更改，可在請求url后添加參數(shù)控制。資源列表返回條目控制參數(shù)名參數(shù)作用max-results控制顯示結果條目的數(shù)量start-index控制返回資源列表的起始條目數(shù)例如：獲取用戶列表接口中，返回 100條數(shù)據(jù)：/ap i/admin/domain/DOMAIN_NAME/usermax-results=1OO返回從第20條開始的

23、10條數(shù)據(jù)：/ap i/admin/domain/DOMAIN_NAME/userstart-index=2O返回從第20條開始的100條數(shù)據(jù)：/ap i/admin/domain/DOMAIN_NAME/usermax-results=100&amp ;start-index=20資源詳情類型：Content-Type 為 application/atom+xml;type=entry 這類資源有固定標簽，這些標簽通常都有特殊含義，如： category :目錄、種類； title :標題； content :內容； summary :摘要。atom:feed/atom:li nkr

24、el="edit":該資源的編輯地址。以用戶的增刪改查為例，示例各種 Feed AP調用步驟用戶的增刪改查接口名稱請求方式請求url獲取用戶列表獲取用戶信息/ap i/admin/domain/DOMAIN_NAME/userGET/ap i/admin/domain/DOMAIN_NAME/user/USER_NAME添加用戶P OST/ap i/admin/domain/DOMAIN_NAME/user修改用戶信息PUT/ap i/admin/domain/DOMAIN_NAME/user/USER_NAME刪除用戶DELETE/ap i/admin/domain/DO

25、MAIN_NAME/user/USER_NAME說明:USER NAME為用戶名。DOMAIN NAME為用戶所在的域。例如用戶的郵件地址為，那么USER_NAME為test , DOMAIN_NAME為。用戶Atom部分屬性列表標簽（根為 atom:entry對應字段例子添加修改atom:title用戶賬戶名testatom:content用戶真實名小明創(chuàng)建時間，ATOM格式2010-04-20T10:30:53+0atom: up dated8:00eyo u:p assword密碼myp asswordPHP調用用戶操作API示例<phpdefine('A PI_KEY&#

26、39;,");AP l_KEY . $auth_timestam p).);$htt p->setUrl(SERVER . 'ap i/service/auth/get_token');$htt p->setMethod(Htt pRequest:METH _P OST);$htt p->set Po stFields($ postdata);$htt p->setHeaders(array('Content-T ype' => 'app lication/x-www-form-urlencoded');其

27、中auth_signature簽名的算法為:$htt p->send();$auth_token = $htt p->getRes po nseBody();MD5(A PI_SECRET + auth_key + auth_timesta mp + auth_token)。$auth_signature = md5(A PI_SECRET . AP I_KEY . $auth_timesta mp . $auth_token); '="' . rawurlencode($v).'"'''.im plode(

28、9;, ', $tm p);'vtitle>' . $title . 'v/title>'.'<entry xmlns="" xmlns:eyou="">'.'vcontent' . $name . '</content>'.'veyo u:p assword>' . $p assword . 'v/eyo u:p assword>'.'veyou:admin_t yp e>

29、' . $admin_t ype . 'v/eyou:admin_t yp e>'.'</entry>'$http->setUrl(SERVER . 'api/admin/domain/'. $domain_name . '/user'); 'api/admin/domain/'$domain_name . '/user/' . $user_name); 'api/admin/domain/'. $domain_name . '/user');'ventry xmlns="" xmlns:eyou="">'.'vcontent' . $new content . 'v/content>