## 一、開通接口 需先從卡平臺獲得接口交互的appId和appSecret； api服務地址：http://ip:port/oauth/service， >[danger] > 1、api服務地址+api的url組合，構成了客戶端api請求的完整地址； > 2、比如平臺內置提供了一個用于測試驗證的api，其url是/test/validation，那么實際完整的請求地址應當為：http://ip:port/oauth/service/test/validation > 3、開戶的過程參考：[http://www.hmoore.net/fang2099/erp-scm-mes-hr-oa/1589749](http://www.hmoore.net/fang2099/erp-scm-mes-hr-oa/1589749) ## 二、技術要求 1.所有接口的請求，采用httpPost方式提交，發出http請求的時候，請求content-type需設定為：application/x-www-form-urlencoded;charset=UTF-8 ，參數按照普通表單參數傳值，不必包裹成一個json字符串； 2.所有接口的響應，采用json格式，編碼為UTF-8，響應的content-type為：application/json;charset=UTF-8）； 3.提供ip白名單功能，僅供授權的ip調用； 4.每個對外提供服務的api，都必須包含的參數為appId及timeStamp，為了確保不被外部不法分子惡意篡改請求，請求參數中絕對不能包含appSecret； 5.每個對外提供服務的api，都必須包含一個sign參數，該參數是通過算法計算出來的值，具體算法參考后續簽名算法章節； 6.考慮服務器承載量，目前限制每個ip訪問接口頻率不得超過1秒10次，超過這個次數，該ip將會被禁止調用，程序中不得做高頻率輪詢； 7.接口服務自身的設計與開發是基于BASE理論。因此，也強烈建議代碼編寫者遵循該理論；程序開發者必需考慮接口服務器因機房網絡故障、域名解析故障、例行檢修、程序升級、依賴服務中斷等因素導致當前服務不可用。因此，業務邏輯的編寫必須嚴格的核對響應碼，并且必須編寫消費接口服務的異常分支邏輯； >[danger] 只有responseCode為1，才能說明這個api執行成功了，否則，都是失敗，只是失敗原因各不相同； ## 三、時間戳格式 1.獲取從1970, 00:00:00開始到當前的毫秒數(13位) 2.每個api請求的有效時間為3分鐘,所以,務必確保當前服務請求的時間是準確的； ## 四、簽名算法 假設：paramstrings = 當前api的所有參數(除sign外)，根據參數名升序排序，以“參數名=值&”的方式連接起來； 結果：sign = md5(md5(paramstrings)+appSecret) >[danger] 注意：是雙層md5加密，中間那個"+"僅表示兩段字符相連,并不包括該符號本身； ## 五、接口限流 對外服務的每個API接口當訪問頻率或者并發量超過其承受范圍時候,我們就必須考慮限流來保證接口的可用性或者降級可用性.以防止非預期的請求對系統壓力過大而引起的系統癱瘓； ### 算法 平臺采用令牌桶算法進行限流，針對每個appId（客戶端），都限制其每秒鐘可以接收的請求數，確保整個對外服務正常有序； 令牌桶算法的原理是系統會以一個恒定的速度往桶里放入令牌，而如果請求需要被處理，則需要先從桶里獲取一個令牌，當桶里沒有令牌可取時，則拒絕服務；  ### 設置 系統參數配置中，可以設定每個appId每秒請求數限制：  ### 注意 >[danger]正常的訪問平臺是通過接口限流策略，實現了業務可用性保障；對應非正常的訪問，平臺則通過DDOS防御設施，實現業務可用性保障； ## 六、例程 為了方便客戶端編程，這里提供了一個完整的客戶端調用api示范，基于java代碼編寫，您可以直接復制過去，修改參數運行；您可以向我們索取代碼； 具體接口，請參考下面的章節；