## 一、開通服務 需先從平臺獲得接口交互的appId和appSecret； api服務地址：[http://ip](http://ip/):port/api/rayoauth； ## 二、技術要求 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，都必須在請求頭部包含參數`rayOauthServerAppId`（值是您拿到的appId）及`rayOauthServerTimeStamp`（值是時間戳，參考時間戳格式取值），為了確保不被外部不法分子惡意篡改請求，請求參數中絕對不能包含appSecret； 5.每個對外提供服務的api，都必須在請求頭部包含一個`rayOauthServerSignature`參數，該參數是通過算法計算出來的值，具體算法參考后續簽名算法章節； 6.考慮服務器承載量，目前限制每個ip訪問接口頻率不得超過1秒10次（可配置），超過這個次數，該請求將會被過濾，程序中不得做高頻率輪詢； 7.接口服務自身的設計與開發是基于BASE理論。因此，也強烈建議代碼編寫者遵循該理論；程序開發者必需考慮接口服務器因機房網絡故障、域名解析故障、例行檢修、程序升級、依賴服務中斷等因素導致當前服務不可用。因此，業務邏輯的編寫必須嚴格的核對響應碼，并且必須編寫消費接口服務的異常分支邏輯； ## 三、時間戳格式 1.獲取從1970, 00:00:00開始到當前的毫秒數(13位，如java版本的：new Date().getTime()即可) ； 2.每個api請求的有效時間為3分鐘（可配置），所以需確保當前服務請求發起端的時間有效； ## 四、簽名算法 假設：paramstrings = 當前api的所有參數(除rayOauthServerSignature外)，根據參數名升序排序，以“參數名=值&”的方式連接起來； 結果：rayOauthServerSignature= md5(md5(paramstrings)+appSecret) >[danger] 注意： > 1、是雙層md5（32位小寫）加密，中間那個"+"僅表示兩段字符相連,并不包括該符號本身； > 2、參數包括了請求頭和請求體里面的所有參數； ## 五、接口限流 支持接口限流算法，在參數配置中，可配置每客戶端每秒最大請求數，超過部分將被過濾限制掉；  ## 六、安全機制 除常規的安全機制（IP白名單、限流、api授權、時間戳校驗、參數簽名驗證）等之外，平臺還提供可選的防重放攻擊等高級安全機制，但考慮實際必要性和性能，酌情啟用； ``` rayframework.oauthserver.advanced-security-enabled=false ``` ## 七、資源優化 考慮到有些用戶，對自身調用程序未做任何控制，導致大量無效請求占用服務器資源，故提供策略間歇性封鎖ip的功能； ## 八、實例代碼 ``` public class ClientSample { public static void main(String[] args) { Log4jV2Util.initLog4jV2TestEnv(); String hostUrl = "http://yourapidomain:8080/rayiot/api/rayoauth"; String apiUrl = "/sample/asyn"; String appId = "ray40c9903c6"; String appSecret = "46bacebf-f63c-41cc-b29c-5812994a5e83"; Map<String, String> paramap = new HashMap(); paramap.put("testParamInt", "1"); paramap.put("testParamString", "2"); String result = OauthCaller.call(hostUrl, apiUrl, appId, appSecret, paramap); Logger logger = LoggerFactory.getLogger(ClientSample.class); logger.debug(result); } } ```