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

/產(chǎn)品/項(xiàng)目名稱保密級(jí)別郵件系統(tǒng)機(jī)密產(chǎn)品/項(xiàng)目版本最后更新日期81032014-09-12郵件系統(tǒng)V8接口文檔北京億中郵信息技術(shù)有限公司版權(quán)所有侵權(quán)必究?jī)H供內(nèi)部使用修訂記錄日期修訂版本修改描述作者2012-11-150.1初稿劉暢2013-10-210.2初稿王永杰2014-04-220.3更新錯(cuò)誤的5值傅春花2014-09-120.4重新編輯整理文檔周盈妤目錄\o"1-3"\h\u\l267521接口簡(jiǎn)介 267524\l145342認(rèn)證概述 145345\l210452.1認(rèn)證方式的分類 210455\l164042.2認(rèn)證方式的選擇 164046\l320352.3認(rèn)證原理 320356\l210883認(rèn)證方法詳解及示例 210886\l31053.1 31056\l221183.2 221186\l259053.2.1的認(rèn)證方法： 259056\l131693.2.2的認(rèn)證方法： 131698\l200903.2.3申請(qǐng)會(huì)話： 200909\l191824接口調(diào)用示例 1918212\l41184.2調(diào)用 411812\l265024.2.1資源概述 2650212\l105444.2.2以用戶的增刪改查為例，示例各種調(diào)用步驟 1054413\l56845附表 5684171接口簡(jiǎn)介指郵件系統(tǒng)所提供的接口。調(diào)用接口流程圖：申請(qǐng)申請(qǐng)獲取認(rèn)證認(rèn)證認(rèn)證認(rèn)證認(rèn)證認(rèn)證（需要申請(qǐng)）調(diào)用接口調(diào)用接口為了保證調(diào)用的安全性等因素，要求調(diào)用方必須持有。此需要由調(diào)用方向方申請(qǐng)此。方在接受調(diào)用方申請(qǐng)后，會(huì)頒發(fā)以及一個(gè)與之配對(duì)的。調(diào)用方必須記錄此以及。是提供方（例如部署了郵件系統(tǒng)的單位）頒發(fā)給調(diào)用方（例如需要獲取郵件系統(tǒng)數(shù)據(jù)的系統(tǒng)）的身份識(shí)別串。此事一個(gè)郵件地址格式的字符串，例如：。提供方頒發(fā)給調(diào)用方身份識(shí)別串對(duì)應(yīng)的秘鑰。此是一個(gè)32字節(jié)的字符串，例如35c51333d1e9b36802c5d79b8。接口分為兩大類：（1）用戶提供（單點(diǎn)登錄）的。（2）用于郵件資源操作的。2認(rèn)證概述為保證的安全性，防止非法的調(diào)用，識(shí)別調(diào)用者身份的合法性，在調(diào)用過(guò)程中必須先進(jìn)行認(rèn)證。2.1認(rèn)證方式的分類支持三種認(rèn)證方式，分別是、和方式。是符合規(guī)范的標(biāo)準(zhǔn)認(rèn)證方式，而和是自定義的規(guī)范。2.2認(rèn)證方式的選擇由于認(rèn)證方式比較復(fù)雜，所以不建議使用認(rèn)證方式，除非您的業(yè)務(wù)必須要求遵循方式認(rèn)證。比安全性更高，但是也會(huì)更復(fù)雜一些，需要先申請(qǐng)會(huì)話。如果您對(duì)調(diào)用的安全性要求較高，那么建議您使用認(rèn)證方式。如果您對(duì)調(diào)用的安全性要求不是非常高（比如郵件系統(tǒng)部署在內(nèi)網(wǎng)，只在內(nèi)網(wǎng)使用），那么可以使用認(rèn)證方式。2.3認(rèn)證原理認(rèn)證的原理是：調(diào)用方在調(diào)用的同時(shí)需要附加傳遞認(rèn)證信息（、、簽名等），在接收到調(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ù)用來(lái)生成認(rèn)證信息，例如認(rèn)證方式需要先申請(qǐng)會(huì)話。3認(rèn)證方法詳解及示例3.1標(biāo)準(zhǔn)的認(rèn)證方式。詳見官方文檔以及5849。3.2認(rèn)證方式對(duì)于和兩種接口稍有不同，傳遞認(rèn)證信息是通過(guò)的方式，則是通過(guò)把認(rèn)證信息參數(shù)放到的頭中傳遞。3.2.1的認(rèn)證方法：將如下表格中的參數(shù)以參數(shù)的形式傳遞給。注意：由于是通過(guò)方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行處理。參數(shù)名參數(shù)說(shuō)明認(rèn)證方式。為固定的值。系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳?xí)?。此?huì)話需要在調(diào)用之前申請(qǐng)。申請(qǐng)方法見申請(qǐng)會(huì)話。簽名。算法：5(++++)的目標(biāo)用戶的郵件地址。此參數(shù)并不是認(rèn)證信息參數(shù)，但是由于在計(jì)算簽名的時(shí)候需要用到，所以這這里列出。的認(rèn)證完整示例 假設(shè)如下參數(shù)的值為：：：35c51333d1e9b36802c5d79b8：申請(qǐng)到的會(huì)話：548系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳：1262307600計(jì)算簽名：5(35c51333d1e9b36802c5d79b81262307600548)計(jì)算的結(jié)果：46a8f76c21e86811d7b2260339b1此時(shí)得到方式傳送所需的五個(gè)參數(shù)：:;:;:1262307600;:548;:46a8f76c21e86811d7b2260339b1;對(duì)五個(gè)參數(shù)分別作處理，得到如下結(jié)果：:;:40;:1262307600;:5483D;:46a8f76c21e86811d7b2260339b1;那么的請(qǐng)求為：3.2.2的認(rèn)證方法：將如下表格中的參數(shù)放到的頭中傳遞給。（的認(rèn)證中，簽名的計(jì)算不需要，此處與不同）注意：由于是通過(guò)頭方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行處理。參數(shù)名參數(shù)說(shuō)明認(rèn)證方式。為固定的值。系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳?xí)?。此?huì)話需要在調(diào)用之前申請(qǐng)。申請(qǐng)方法見申請(qǐng)會(huì)話。簽名。算法：5(+++)的認(rèn)證完整示例假設(shè)如下參數(shù)的值為：：：35c51333d1e9b36802c5d79b8申請(qǐng)到的會(huì)話：548系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳：1262307600計(jì)算簽名：5(35c51333d1e9b36802c5d79b81262307600548)計(jì)算的結(jié)果：3e7f0e9a79c51f1a67d749908a3此時(shí)得到頭中傳送所需的五個(gè)參數(shù)：:;:;:1262307600;:548;:3e7f0e9a79c51f1a67d749908a3;對(duì)五個(gè)參數(shù)分別作處理，得到如下結(jié)果：:;:40;:1262307600;:5483D;:3e7f0e9a79c51f1a67d749908a3;那么（以獲取的未讀郵件數(shù)量為例）的請(qǐng)求數(shù)據(jù)包為：4011.0::"40","1262307600","5483D","3e7f0e9a79c51f1a67d749908a3"3.2.3申請(qǐng)會(huì)話：在認(rèn)證方式中，和都需要提前申請(qǐng)用于傳參和計(jì)算簽名，申請(qǐng)會(huì)話的請(qǐng)求為：申請(qǐng)會(huì)話需要向上述發(fā)送一個(gè)為的請(qǐng)求，此請(qǐng)求必須包含如下表格中的參數(shù)。注意：由于是通過(guò)頭方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行處理。參數(shù)名參數(shù)說(shuō)明系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳簽名。算法：5(++)(非必需)的目標(biāo)用戶的郵件地址。（時(shí)需要此參數(shù)，不需要）上表中的前三個(gè)參數(shù)必須傳遞，除了必須傳遞的參數(shù)之外，還可以附加傳遞其它附加參數(shù)，所有的附加參數(shù)都會(huì)被記錄在郵件系統(tǒng)中，以供下一步的驗(yàn)證使用（例如要求必須傳遞一個(gè)附加參數(shù)），但是要注意，附加的參數(shù)名不能以開頭，以防止和必須傳遞的參數(shù)沖突。如果申請(qǐng)成功，會(huì)話將會(huì)被放到請(qǐng)求的應(yīng)答中輸出。成功或者失敗的應(yīng)答及說(shuō)明詳見附表1。獲取完整示例假設(shè)如下參數(shù)的值為：：：35c51333d1e9b36802c5d79b8系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳：1262307600計(jì)算簽名：5(35c51333d1e9b36802c5d79b81262307600)計(jì)算的結(jié)果：36b60456761a978387312此時(shí)得到所必須的三個(gè)參數(shù)：:;:1262307600;:36b60456761a978387312;申請(qǐng)時(shí)需要附加參數(shù)：:;對(duì)以上參數(shù)分別作處理，得到如下結(jié)果：:40;:1262307600;:3e7f0e9a79c51f1a67d749908a3;:40;（申請(qǐng)時(shí)需要）那么，請(qǐng)求數(shù)據(jù)包為：:::131436b60456761a978387312請(qǐng)求數(shù)據(jù)包為：:::131436b60456761a978387312403.3認(rèn)證方式與認(rèn)證方式的區(qū)別是認(rèn)證信息參數(shù)為，并且不需要申請(qǐng)會(huì)話。也就是說(shuō)，認(rèn)證方式就是把認(rèn)證方式中的參數(shù)變?yōu)?，并且把申?qǐng)會(huì)話的步驟去掉，同時(shí)把傳遞的認(rèn)證參數(shù)中涉及會(huì)話的參數(shù)去掉（包括簽名中的會(huì)話）。對(duì)于認(rèn)證過(guò)程來(lái)說(shuō)，除了沒有會(huì)話，其余的處理與一致。4接口調(diào)用示例接口分為單點(diǎn)登陸的和郵件資源操作的。4.1單點(diǎn)登陸4.1.1請(qǐng)求和方法4.1.2請(qǐng)求參數(shù)及步驟詳見的認(rèn)證完整示例。4.2調(diào)用4.2.1資源概述以資源的形式提供調(diào)用。例如獲取1這個(gè)用戶的信件列表的資源地址為：1接口從資源類型來(lái)說(shuō)分為兩大類：1.資源列表類型，如域列表、用戶列表等；2.具體的資源詳情類型，如域詳情、用戶詳情等。資源列表類型：為這類資源通常支持查詢、分頁(yè)，是資源詳情的集合：：結(jié)果總數(shù)：開始位置：每頁(yè)個(gè)數(shù)[""]：當(dāng)前頁(yè)[""]：第一頁(yè)[""]：前一頁(yè)[""]：下一頁(yè)[""]：最后一頁(yè)注意：資源列表類型默認(rèn)返回10條數(shù)據(jù)，如需更改，可在請(qǐng)求后添加參數(shù)控制。資源列表返回條目控制參數(shù)名參數(shù)作用控制顯示結(jié)果條目的數(shù)量控制返回資源列表的起始條目數(shù)例如：獲取用戶列表接口中，返回100條數(shù)據(jù)：？100返回從第20條開始的10條數(shù)據(jù)：？20返回從第20條開始的100條數(shù)據(jù)：？10020資源詳情類型：為這類資源有固定標(biāo)簽，這些標(biāo)簽通常都有特殊含義，如：：目錄、種類；：標(biāo)題；：內(nèi)容；：摘要。[""]：該資源的編輯地址。4.2.2以用戶的增刪改查為例，示例各種調(diào)用步驟用戶的增刪改查接口名稱請(qǐng)求方式請(qǐng)求獲取用戶列表獲取用戶信息添加用戶修改用戶信息刪除用戶說(shuō)明：為用戶名。為用戶所在的域。例如用戶的郵件地址為，那么為，為。用戶部分屬性列表標(biāo)簽（根為）對(duì)應(yīng)字段例子添加修改用戶賬戶名√×用戶真實(shí)名小明√√:創(chuàng)建時(shí)間，格式2010-04-20T10:30:53+08:00××密碼√√調(diào)用用戶操作示例<('','');定義認(rèn)證信息('','e158163f9649b4f73b6e06c69f7');定義認(rèn)證信息('','');定義郵件服務(wù)器$=();定義當(dāng)前時(shí)間戳{{{認(rèn)證信息$=;$='';申請(qǐng)，需要向發(fā)送一個(gè)為的請(qǐng)求，此請(qǐng)求必須如下中的三個(gè)參數(shù)：$=(''=>,''=>$,''=>5(..$),);$>(.'');$>();$>($);$>((''=>''));$>();$=$>();獲取到會(huì)話認(rèn)證傳遞認(rèn)證信息是把認(rèn)證信息參數(shù)放到的頭中傳遞。認(rèn)證信息參數(shù)包含,,,,.其中簽名的算法為：5(+++)。$=5(..$.$);獲取簽名$=(''=>,''=>$,系統(tǒng)當(dāng)前的整數(shù)時(shí)間戳''=>$,會(huì)話''=>$,簽名);$=();($$>$v){$[]=$k.'="'.($v).'"';注意：由于是通過(guò)頭方式傳遞認(rèn)證信息參數(shù)，所以所有的參數(shù)的值都必須要進(jìn)行處理。}$=$.''.(',',$);得到認(rèn)證/*例如$的輸出結(jié)果為："40","1262307600","5483D","3e7f0e9a79c51f1a67d749908a3"*/}}}{{{添加新用戶方法$='1';$='1';$='100100100';$=0;$='';$='<"1.0""8"?>'.'<"""">'.'<>'.$.'<>'.'<>'.$.'<>'.'<>'.$.'<>'.'<>'.$.'<>'.'<>';$>(.''.$.'');根據(jù)接口的請(qǐng)求設(shè)置$>();根據(jù)接口的請(qǐng)求方式設(shè)置請(qǐng)求方法$>($);$>((''=>$));在頭部傳遞認(rèn)證信息$>();$>();返回'200'代表成功，應(yīng)答代碼列表參考附表2$>();成功時(shí)返回新用戶數(shù)據(jù)，失敗時(shí)提示錯(cuò)誤原因。}}}{{{獲取用戶信息方法（資源詳情類型）$='1';$='';$>(.''.$.''.$);根據(jù)接口的請(qǐng)求設(shè)置$>();根據(jù)接口的請(qǐng)求方式設(shè)置請(qǐng)求方法$>((''=>$,在頭部傳遞認(rèn)證信息''=>'',獲取資源詳情類型));$>();$>();返回'200'代表成功，應(yīng)答代碼列表參考附表2$>();成功時(shí)返回用戶數(shù)據(jù)信息，失敗時(shí)提示錯(cuò)誤原因。}}}{{{獲取用戶列表方法（資源列表類型）$='';$>(.''.$.'');根據(jù)接口的請(qǐng)求設(shè)置$>();根據(jù)接口的請(qǐng)求方式設(shè)置請(qǐng)求方法$>((''=>$,在頭部傳遞認(rèn)證信息''=>'',獲取資源列表類型));$>();$>();返回'200'代表成功，應(yīng)答代碼列表參考附表2$>();成功時(shí)返回用戶列表數(shù)據(jù)信息，失敗時(shí)提示錯(cuò)誤原因。