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

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

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

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

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

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

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

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

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

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

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

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

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

13、f0e9a79c51f1a67d74ac99fad08a3 ;對(duì)五個(gè)參數(shù)分別作RawUrlEncode處理，得到如下結(jié)果:auth_t ype auth_keyauth ;ap itest% ;auth_timesta mp:00 ;auth tokenauth_signature:nq54a Hp ZseNWPwxwfrklZO8uGSU%3D ;:3e7f0e9a79c51f1a67d74ac99fad08a3 ;那么Feed API （以獲取的未讀郵件數(shù)量為例）的HTTP請(qǐng)求數(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"申請(qǐng)會(huì)話Token：在eYouAuth認(rèn)證方式中，SSO AP和Feed API都需要提前申請(qǐng) Token用于傳參和計(jì)算簽 名，申請(qǐng)會(huì)話Token的請(qǐng)求URL為：申請(qǐng)會(huì)話Token需要向上述 URL發(fā)送一個(gè)content-type 為application/x-www-form-ur

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

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

17、的三個(gè)參數(shù):auth_key ;auth_timesta mp: 00 ;36b60aa4fcaf56cd761a9bed ;auth_signatureSSO API申請(qǐng)Token時(shí)需要附加email參數(shù):email ;對(duì)以上參數(shù)分別作 RawUrlEncode處理，得到如下結(jié)果:auth_keyap itest% ;auth_timesta mp:00 ;auth_signatureemail:3e7f0e9a79c51f1a67d74ac99fad08a3 ;:test% ;（SSO API申請(qǐng) Token 時(shí)需要） 那么，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請(qǐng)求數(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認(rèn)證方式與eYouAuth認(rèn)證方式的區(qū)別是認(rèn)證信息參數(shù)auth_type為simple,并且不需要申請(qǐng)會(huì)話Token。也就是說，eYouSimpleAuth 認(rèn)證方式就是把 eYouAuth 認(rèn)證方式中的 auth_type 參數(shù)變?yōu)?simple,并且把申請(qǐng)會(huì)話 Token的步驟去掉，同時(shí)把傳遞的認(rèn)證參數(shù)中涉及會(huì)話Token的參數(shù)去掉（包括簽名中的會(huì)話 Token）。對(duì)

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

21、Type 為 application/atom+xml;type=feed 這類資源通常支持查詢、分頁，是資源詳情的集合：/atomfeed/opensearch:totalResults :結(jié)果總數(shù) /atomfeed/opensearch:startIndex :開始位置 /atomfeed/opensearch:itemsPerPage :每頁個(gè)數(shù) /atom:feed/atom:li nkrel="self":當(dāng)前頁 /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":最后一頁注意：資源列表類型默認(rèn)返回10條數(shù)據(jù)，如需更改，可在請(qǐng)求url后添加參數(shù)控制。資源列表返回條目控制參數(shù)名參數(shù)作用max-results控制顯示結(jié)果條目的數(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 這類資源有固定標(biāo)簽，這些標(biāo)簽通常都有特殊含義，如： category :目錄、種類； title :標(biāo)題； content :內(nèi)容； summary :摘要。atom:feed/atom:li nkr

24、el="edit":該資源的編輯地址。以用戶的增刪改查為例，示例各種 Feed AP調(diào)用步驟用戶的增刪改查接口名稱請(qǐng)求方式請(qǐng)求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部分屬性列表標(biāo)簽（根為 atom:entry對(duì)應(yīng)字段例子添加修改atom:title用戶賬戶名testatom:content用戶真實(shí)名小明創(chuàng)建時(shí)間，ATOM格式2010-04-20T10:30:53+0atom: up dated8:00eyo u:p assword密碼myp asswordPHP調(diào)用用戶操作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>