1、安徽電信服務總線接口規范安徽電信有限公司2014年02月版本記錄版本號時間記錄人變更原因變更描述V0.12014-1-5李超初始V0.22014-2-22李超修訂增加接口參數描述第1章概述41.1 概述41.2 目標41.3 規范使用對象及說明41.4 名詞解釋4第2章服務設計原則52.1 接口協議統一原則52.3 服務定義唯一性原則62.4 服務無狀態原則62.5 服務部署原則62.6 服務組合原則62.7 報文內容處理的原則72.8 由入參設計原則72.9 規則校驗的原則82.10 數據量原則82.11 同步調用原則82.12 統一入口原則82.13 持久化原則8第3章服務接入規范93.1

2、 調用方式93.2 參數說明103.2.1 系統級參數103.3 返回業務功能12第4章安全控制134.1 訪問鑒權134.2 傳輸加密14第5章異常分類編碼14第6章服務注冊、注銷、變更、調用流程156.1 服務注冊的流程166.2 服務注冊的內容166.3 測試環境服務注冊的流程17第7章服務治理187.1 目標187.2 檢查方法187.3 服務監控的指標197.4 服務目錄樹20第1章概述1.1 概述本規范明確了安徽電信服務總線接入及服務使用的標準和規范，為服務使用方和服務提供方提供開發參考。1.2 目標本規范為了指導各業務系統與服務總線平臺的對接，實現以下目標：1）當服務總線接入業務

3、系統服務時，為該服務提供方提供開發依據。2）當服務使用方調用服務總線提供的服務時，為該服務使用方提供開發依據。3）為服務使用過程中安全及控制提供標準和參考。1.3 規范使用對象及說明本規范適用于所有新建或改造的服務接口，均需要遵守本規范約定。1.4 名詞解釋1）服務提供方：提供原始服務，并將服務發布到服務總線的內部業務系統、第三方企業或個人。2）服務使用方：使用服務總線上的服務進行應用開發的內部應用系統、第三方企業或個人。3）服務商：平臺為統一管理服務的提供方和使用方，綜合其統稱為服務商。4）服務：服務是執行可重復任務的可發現資源，由外部化的服務規范進行描述。服務可分為技術服務和業務服務兩種。

4、第2章服務設計原則由于各個系統和平臺之間存在差異性，為確保安徽電信服務總線的穩定高效，服務設計原則如下：2.1 接口協議統一原則所有服務的接口均基于Http協議。服務提供方和服務使用方必須同時使用同一種類型的技術來進行開發和調用，調用的服務通過HTTPURL中特定屬性進行標識，具體見接口協2.2 數據格式統一原則服務的接口數據包含業務所有的業務數據，數據采用JSON格式表示，并且符合相應的JSONSchema。服務提供方和服務消費方必須同時使用同一種格式進行數據交互。2.3 服務定義唯一性原則一個服務應該只實現一個業務功能，業務功能的區別通過服務編碼來區分，不應通過定義不同的業務數據在同一個服

5、務編碼下實現不同的業務功能。2.4 服務無狀態原則服務應是無狀態的，兩次請求之間無須狀態和會話的保持，并可以采用輪詢的方式在負載均衡器上進行注冊2.5 服務部署原則服務應是全局的，不應區分本地網、大區等，但可以部署多份用以提供不同優先級的服務。2.6 服務組合原則服務按照服務粒度設計成原子服務和組合服務。原子服務為最細粒度的服務，組合服務由原子服務組合而成。為有效提高組合服務的效率，跨系統的組合服務由服務總線調用不同的原子服務實現組合，系統內的組合服務由服務提供方在應用內部進行組合。2.7 報文內容處理的原則服務請求和返回的的報文應符合JSONSchema格式服務請求方和提供方應采用通用的JS

6、ON解析器來構造和解析數據，JSON不同含義的段落應定義明確含義的字段名稱，相同內容的數據應采用數組來進行描述，雙方可根據JSON名稱和路徑進行精確定位，不應根據字段的順序來獲取字段值，字段值不受字段順序調整的影響。報文統一采用UTF-8進行編碼。2.8 出入參設計原則為提高查詢類服務的通用性和性能，查詢類服務在入參中定義返回字段列表，服務提供方根據入參中指定的字段返回信息。查詢內接口應在入參中定義分頁參數，返回參數中應包含當前頁數、總頁數或是已到最后一頁等信息。返回參數中如返回靜態編碼值時應同時返回此編碼值對應的名稱。2.9 規則校驗的原則服務提供方應對請求報文格式和關鍵信息進行合規性和業務

7、校驗，防止非法訪問和入侵。2.10 數據量原則服務總線所傳遞的單條消息大小原則上不大于1M,否則應建議采用文件傳輸、接口表傳輸、直連等連接方式。2.11 同步調用原則服務調用方和服務提供方采用同步調用的方式進行請求，如需要使用異步調用可采用消息隊列或服務調用方定義異步通知接口來實現。2.12 統一入口原則服務總線對外提供統一的調用地址。2.13 持久化原則服務使用方在使用服務的過程中，由服務總線進行整個過程的日志記錄，并對調用的詳細信息進行持久化，便于對賬和稽核。建議服務調用方和提供方對調用的關鍵信息（如流水號，源地址等）進行持久化。第3章服務接入規范對于服務調用的訪問方式，平臺采用標準的HT

8、TP調用方式。3.1 調用方式接口服務通過http:/ip:port/oip/rest訪問平臺服務。IP和PORT根據實際生產環境情況對外公布。其中/oip/rest保持不變。實例：基于REST的服務請求以使用“查詢BSS用戶短信詳單”服務為例，該服務的具體信息如下：服務名稱：查詢BSS用戶短信詳單；服務編碼：SelectSmsInfo;開發技術：采用HTTP協議技術；請求方式：采用GET/POST都可以調用方信息不變根據上面這些信息，得由服務訪問地址為:GET方式：http:4:7080/oip/rest?send=crm&servCode=1001.OPEN_3R

9、D.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1末位的1”是模擬業務參數。POST方式：4:7080/oip/rest?send=crm&servCode=1001.OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1業務參數的內容放在http的請求體中傳輸3.2 參數說明3.2.1 系統級參數以下參數是由服務總線定義的。表格3-1系統級參數參數名是否必描述需Sendstring是客戶端所屬系統編碼，填寫請參考3.1節（系統

10、標志全部采用此編碼）servCodestring是客戶端需要訪問的服務編碼，由服務總線在注冊后統一提供msgIdstring是由調用方系統按照OIP規則生成的唯一標識次調用的字符串，長度小于64位。生成規則：系統名當前時間戳流水號busiUrlstring是消費方傳遞的業務部分地址App_keyString否服務總線分配的應用標志transactionldString是交易流水號，由調用方生成，多次請求均會包含此信息。格式建議為系統名當前時間戳流水號R1String否動態路由參數1R2String否動態路由參數2R3String否動態路由參數3transactionld:交易流水號。服務請求需

11、經過多個系統或多個系統模塊，為了有效標志由一次業務請求經過的所有調用，服務調用方在請求時生成一唯一的流水號，服務總線在多次調用過程中將會保持此交易流水號一致，服務提供方也應記錄此交易流水號。所有消息日志應統一記錄到統一日志平臺以供事后分析。R1-R3:動態路由參數，為了保持路由的靈活性，調用方可動態添加最多3個路由參數，如版本號，本地網等參數，服務總線根據此參數路由到特定的服務提供方節點上，以滿足試點，灰度發布等場景。3.3 返回業務功能返回參數分為兩部分，一部分為HTTP協議部分，包含了請求的狀態，異常代碼和異常信息，200表示本次請求完成，500表示服務總線調用服務提供方由現異常等；一部分

12、為業務數據，業務數據采用JSON格式，JSON格式需符合JSONSchema的校驗規則，業務異常也在此部分定義。服務總線后臺分析系統將會對請求和返回的報文進行事后分析。第4章安全控制4.1 訪問鑒權服務總線對外提供統一安全控制策略。所有訪問能力開放平臺的服務時，都必須經過平臺的鑒權，鑒權通過后方允許訪問，否則將給與攔截。能力開放的訪問鑒權提供如下幾種策略：服務商鑒權：凡是使用能力開放平臺的服務使用方必須是已注冊的服務商下的一個客戶端。該部分由使用方進行申請，平臺完成注冊，同時為服務使用方分配可使用服務的權限。IP地址鑒權：應用集成平臺支持服務使用方的IP地址身份認證模式。對于不在服務使用方申請

13、的IP地址范圍內產生的服務調用，平臺給予攔截和告警。對于通過多重路由或映射導致不能獲得實際IP地址時，將采用鑒權碼方式替代。摘要式認證：采用標準的HTTP摘要認證方式進行訪問認證，具體介紹見參考文檔OAuth2.0:對于嚴格權限限制的場景，通過OAuth2.0協議進行認證和授權，授權由應用系統統一提供。4.2 傳輸加密對于安全非常高的場合，建議全流程采用HTTPS協議進行加密傳輸，如繳費等場景。第5章異常分類編碼在使用平臺服務的過程中，平臺對不同的異常進行分類，供開發者和使用方在調測及使用過程中參考種類編碼描述正常0成功接口請求方異常2消息格式異常，例如必填參數未填、消息編碼異常等3無效的路由

14、屬性10接口請求超過指定流量9接口請求包大小超過限制6權限異常（例如無權訪問此服務）101重復請求102無效的業務域或業務大類、小類199接口請求方其他異常接口響應方異常8接口響應力超時201接口響應超過指定流量202接口響應包大小超過限制298接口響應力內部異常299接口響應方其他異常平臺異常4調用的服務未發布5調用的服務已注銷7調用的服務已關閉11調用的服務不存在1服務調用失敗398平臺內部異常399平臺其他異常其他異常999其他異常測試異常601測試接口未實現業務定義異常1000如果遇到上述類似異常代碼或信息，可以和平臺維護人員聯系幫助解決第6章服務注冊、注銷、變更、調用流程6.1 服務

15、注冊的流程服務注冊和變更：由服務提供方在ITSM發起申請，經服務評審后，由ITSM調用服務總線提供的能力進行注冊和變更。服務注銷：由服務提供方或服務總線管理方根據實際需求和服務的調用次數等評估后發起，經服務提供方、服務總線管理部門和服務調用方會審后在ITSM中發起下線流程。服務調用：由服務調用方發起，經服務提供方確認和服務評審后在服務總線上進行注冊。服務評審由服務總線管理部門牽頭組織。6.2 服務注冊的內容名稱說明接口名稱接口編碼接口筒要描述請求報文樣例返回報文樣例請求報文格式定義返回報文格式定義接口業務異常列表和描述版本號對應的服務節點注冊服務地址探測報文（可選）是否進行探測（時間，頻度）備

16、用服務地址（在連續失敗或撥測失敗等情況下自動或手工切換服務地址）6.3 測試環境服務注冊的流程測試環境服務注冊由ITSM發起，在完成表單填寫后自動在服務總線上進行處理第7章服務治理7.1目標1、 所有域的服務按照協議規范全部接入服務總線，避免由現服務未在服務總線直接使用。2、 注冊在服務總線上的服務必須符合服務總線的規范，包括接口協議，數據格式，不得私自更改協議或超過注冊的內容升級接口內容7.2 檢查方法1、 按照所有服務全部由服務總線調用或者由F5負載均衡器調用的基本原則，服務管理團隊會定期對主機和F5上服務的調用方IP進行審核，如果由現服務端口由現非服務總線或非F5主機的調用，或者F5主機

17、上服務端口非服務總線的調用，則認為由現了異常的服務調用，由服務提供方提供服務調用日志或版本變化情況進行詳細的解釋。2、 服務接口參數應符合接口規范，服務總線將定期對服務調用異常、失敗、異常代碼等進行統計，給由服務接口的符合度。3、 服務返回的業務數據應符合注冊時提供的JSONSchema,不符合的則認為是注冊信息不全或異常升級。服務總線將定期從服務調用報文中進行格式校驗，對不符合格式的消息請求反饋服務提供方并要求進行說明。7.3 服務監控的指標指標類型運行類調用次數平均調用時長1秒以內調用次數1-5秒以內調用次數5秒以上調用次數調用成功次數調用失敗次數調用超時次數非法調用個數常規類服務注冊個數服務變更個數服務注銷個數規范類異常服務接口個數接口請求不合規個數報文格式不合規個數7.4 服務目錄樹