ESB-服務(wù)規(guī)范

1、南京銀行企業(yè)服務(wù)總線服務(wù)接口規(guī)范版本：v1.0目錄第1章服務(wù)規(guī)范31.1基本規(guī)范31.2SOAP格式規(guī)范31.3報(bào)文總體組成4固定字段5擴(kuò)展字段5請(qǐng)求報(bào)文6響應(yīng)報(bào)文7出錯(cuò)報(bào)文81.4XML格式規(guī)范9請(qǐng)求報(bào)文10響應(yīng)報(bào)文11第2章接口規(guī)范122.1服務(wù)操作定義122.2消息定義132.3字段定義132.5命名空間定義14第1章 服務(wù)規(guī)范1.1 基本規(guī)范Ø 消息格式：SOAPØ SOAP綁定模式：document/literalØ 字符編碼：UTF-81.2 SOAP格式規(guī)范先看一個(gè)SOAP報(bào)文示例：<soapenv:Envelopexmlns:soapenv=

2、"/soap/envelope/"><soap:Headerxmlns:soap="/soap/envelope/"></soap:Header><soapenv:Body><tns:PersonInfoListRequest xmlns:tns="<SEQ_NO>100000000000</SEQ_NO><SERVICE_ID>A6002</ SERVIC

3、E_ID><CHANNEL_ID>2003</ CHANNEL_ID><BANK_CODE>1001000</ BANK_CODE><USER_ID>9999</ USER_ID><TRAN_DATE>20080929</ TRAN_DATE><TRAN_TIME>095050</ TRAN_TIME><INM_CUST_TYPE>1</ INM_CUST_TYPE><INM_FIRST_NO>1</INM_FIRST_NO&g

4、t;<INM_RESULT_SIZE>10</INM_RESULT_SIZE><CERT_NO>lt;/CERT_NO><CERT_TYPE>011</CERT_TYPE><PARTY_NAME>weikai</PARTY_NAME></tns:PersonInfoListRequest></soapenv:Body></soapenv:Envelope>SOAP消息的根元素是信封，信封報(bào)文主要由報(bào)文頭（Header）和報(bào)文本（Bo

5、dy）構(gòu)成，ESB的Web-Service將不使用Header，服務(wù)調(diào)用者可以忽略對(duì)Header的關(guān)注。因此，ESB的有效載荷在SOAP的Body內(nèi)，每個(gè)Body都只有一個(gè)元素（為了便于描述，我們稱它為ESB報(bào)文元素），這個(gè)元素的內(nèi)部的XML（innerXML）即為要關(guān)注的實(shí)際報(bào)文。如果要了解ESB的接口規(guī)格只需簡(jiǎn)單了解ESB報(bào)文元素即可。接口文檔的定義，也是針對(duì)ESB報(bào)文元素進(jìn)行定義的。上例中的報(bào)文元素為：<tns:PersonInfoListRequest xmlns:tns="<SEQ_NO>100000000000</SEQ_NO><CHA

6、NNEL_ID>2003</CHANNEL_ID><BANK_CODE>1001000</BANK_CODE><USER_ID>9999</USER_ID><TRAN_DATE>20080929</TRAN_DATE><TRAN_TIME>095050</TRAN_TIME><INM_CUST_TYPE>1</INM_CUST_TYPE><INM_FIRST_NO>1</INM_FIRST_NO><INM_RESULT_SIZE

7、>10</INM_RESULT_SIZE><CERT_NO>lt;/CERT_NO><CERT_TYPE>011</CERT_TYPE><PARTY_NAME>weikai</PARTY_NAME></tns:PersonInfoListRequest>該報(bào)文本中，最上面幾個(gè)元素（黑體標(biāo)注）為固定字段，所有服務(wù)報(bào)文都有這些字段。固定字段之后是可變字段，可變字段對(duì)于每個(gè)服務(wù)來說都是不一樣的，具體規(guī)格由服務(wù)接口定義規(guī)范定義，其中中間的幾個(gè)元素（斜體標(biāo)注）為擴(kuò)展字段，

8、主要作用是解決各系統(tǒng)對(duì)報(bào)文公共頭信息的特殊要求。1.3 報(bào)文總體組成報(bào)文體字段由三部分組成：Ø 固定字段：每個(gè)服務(wù)都具備的字段，用來描述和標(biāo)識(shí)請(qǐng)求與響應(yīng)報(bào)文。Ø 擴(kuò)展字段：由于固定字段不能保證滿足所有交易的請(qǐng)求與響應(yīng)信息，各系統(tǒng)可以根據(jù)需要對(duì)報(bào)文進(jìn)行擴(kuò)展。Ø 服務(wù)相關(guān)字段：每個(gè)服務(wù)的請(qǐng)求與響應(yīng)字段，即業(yè)務(wù)字段。固定字段固定字段是服務(wù)的元數(shù)據(jù)類型，在模式文件esb.xsd文件中定義，包含了交易所用到的頭信息內(nèi)容，所有通過ESB發(fā)布的WebService服務(wù)，必須繼承固定字段。ESB固定字段定義文件：擴(kuò)展字段擴(kuò)展字段是為了滿足服務(wù)提供者的請(qǐng)求報(bào)文和響應(yīng)報(bào)文中特殊的報(bào)文

9、頭信息而設(shè)定的。各業(yè)務(wù)系統(tǒng)可以根據(jù)需要定制擴(kuò)展字段模式文件，并包含固定字段模式文件。需要注意的是，擴(kuò)展字段模式文件中的命名空間必須保持與固定字段模式文件中的命名空間一致。建議一個(gè)服務(wù)提供者的擴(kuò)展字段模式文件只定義一個(gè)。擴(kuò)展字段模式文件定義示例：<schema targetNamespace=" elementFormDefault="qualified" xmlns="/2001/XMLSchema" xmlns:esb="<!- 導(dǎo)入ESB報(bào)文頭定義文件 -><include

10、schemaLocation="././Common/Schema/esb.xsd"/><!- ECIF系統(tǒng)請(qǐng)求擴(kuò)展頭 -><complexType name="ECIFRequestBase"><complexContent><extension base="esb:RequestBase"><sequence><!- 擴(kuò)展字段定義部分 -><!- 客戶類型 01：表示個(gè)人客戶信息；02：表示公司客戶信息；00：ECIF系統(tǒng)預(yù)留； -><

11、element minOccurs="1"maxOccurs="1" name="INM_CUST_TYPE" nillable="false"><simpleType><restriction base="string"><minLength value="2"/><maxLength value="2"/></restriction></simpleType></ele

12、ment></sequence></extension></complexContent></complexType>請(qǐng)求報(bào)文固定字段中文名稱英文名稱必填備注交易流水號(hào)SEQ_NON交易流水交易號(hào)SERVICE_IDN服務(wù)交易編號(hào)，細(xì)粒度交易無需填寫渠道代號(hào)CHANNEL_IDY請(qǐng)求渠道號(hào)機(jī)構(gòu)號(hào)BANK_CODEY請(qǐng)求機(jī)構(gòu)號(hào)操作員USER_IDY請(qǐng)求操作員號(hào)授權(quán)操作員AUTH_IDN授權(quán)操作員號(hào)請(qǐng)求日期TRAN_DATEY格式Y(jié)YYYMMDD，如20110810請(qǐng)求時(shí)間TRAN_TIMEY格式HHMMSSNNN，如092031218認(rèn)證信息

13、AUTH_CONTEXTN認(rèn)證信息，暫不使用示例<tns:PersonInfoListRequestxmlns:tns="<SEQ_NO>100000000000</SEQ_NO><SERVICE_ID/><CHANNEL_ID>2003</CHANNEL_ID><BANK_CODE>1001000</BANK_CODE><USER_ID>9999</USER_ID><TRAN_DATE>20080929</TRAN_DATE><TRAN_T

14、IME>095050</TRAN_TIME><INM_CUST_TYPE>1</INM_CUST_TYPE><INM_FIRST_NO>1</INM_FIRST_NO><INM_RESULT_SIZE>10</INM_RESULT_SIZE><CERT_NO>lt;/CERT_NO><CERT_TYPE>011</CERT_TYPE><PARTY_NAME>weikai</PARTY_NAME><

15、/tns:PersonInfoListRequest>響應(yīng)報(bào)文固定字段中文名稱英文名稱必填備注交易流水號(hào)SEQ_NON交易流水服務(wù)號(hào)SERVICE_IDN即交易號(hào)，對(duì)于細(xì)粒度服務(wù)不需要填寫機(jī)構(gòu)號(hào)BANK_CODEN請(qǐng)求操作員所屬機(jī)構(gòu)號(hào)響應(yīng)日期TRAN_DATEY格式Y(jié)YYYMMDD，如20110810響應(yīng)時(shí)間TRAN_TIMEY格式HHMMSSNNN，如092031218交易狀態(tài)TRAN_STATUSYCOMPLETE表示成功，F(xiàn)AIL表示失敗失敗碼ERROR_CODEN交易失敗時(shí)填寫失敗描述ERROR_MSGN交易失敗時(shí)填寫交易返回碼RET_CODEN交易成功，同時(shí)需要返回響應(yīng)碼時(shí)，可

16、填寫交易返回信息描述RET_MSGN交易成功，同時(shí)需要返回響應(yīng)碼時(shí)，可填寫示例<ser:PersonListResponsexmlns:ser="<SEQ_NO>100000000000000</SEQ_NO><BANK_CODE>string</BANK_CODE><TRAN_DATE>20080929</TRAN_DATE><TRAN_TIME>095050</TRAN_TIME><TRAN_STATUS>COMPLETE</TRAN_STATUS><

17、;INM_CUST_TYPE>st</INM_CUST_TYPE><INM_FIRST_NO>string</INM_FIRST_NO><INM_RESULT_SIZE>string</INM_RESULT_SIZE><CUST_NAME>張飛</CUST_NAME><CUST_EN_NAME>ZhangFei</CUST_EN_NAME></ser:PersonListResponse>出錯(cuò)報(bào)文ESB系統(tǒng)內(nèi)部錯(cuò)誤，全部通過SOAP Fault返回出錯(cuò)報(bào)文，包含以下信息

18、：Faultcode：錯(cuò)誤碼Faultstring：錯(cuò)誤信息描述服務(wù)調(diào)用者可以通過捕獲SOAPFaultException，獲取錯(cuò)誤信息。返回出錯(cuò)報(bào)文<ser:PersonListResponsexmlns:ser="<SEQ_NO>100000000000000</SEQ_NO><BANK_CODE>string</BANK_CODE><TRAN_DATE>20080929</TRAN_DATE><TRAN_TIME>095050</TRAN_TIME><TRAN_STATU

19、S>FAIL</TRAN_STATUS><ERROR_CODE>CIF5557</ERROR_CODE><ERROR_MSG>客戶不存在</ERROR_MSG><INM_CUST_TYPE>st</INM_CUST_TYPE><INM_FIRST_NO>string</INM_FIRST_NO><INM_RESULT_SIZE>string</INM_RESULT_SIZE></ser:PersonListResponse>SOAP出錯(cuò)報(bào)文<

20、;soapenv:Envelopexmlns:soapenv="/soap/envelope/"><soapenv:Header /><soapenv:Body><soapenv:Faultxmlns:fault=""><faultcode>E001</faultcode><faultstring>the fault string</faultstring></soapenv:Fault></soa

21、penv:Body></soapenv:Envelope>1.4 XML格式規(guī)范先看一個(gè)XML報(bào)文示例：<Transaction> <HEAD> <SEQ_NO>101000059173</SEQ_NO> <SERVICE_ID>0202</SERVICE_ID> <CHANNEL_ID>ECIF</CHANNEL_ID> <BANK_CODE>9957</BANK_CODE> <USER_ID>99957018</USER_ID>

22、<TRAN_DATE>20111108</TRAN_DATE> <TRAN_TIME>152859843</TRAN_TIME> <EXT_HEAD> <EXT_PIN/> </EXT_HEAD> </HEAD> <BODY> <KEHHAO>1025919289</KEHHAO> </BODY> </Transaction>該報(bào)文本中，HEAD標(biāo)簽中上面幾個(gè)元素（黑體標(biāo)注）為固定字段，所有服務(wù)報(bào)文都有這些字段。固定字段之后是可擴(kuò)展字段，可

23、擴(kuò)展字段對(duì)于每個(gè)服務(wù)來說都是不一樣的，具體規(guī)格由服務(wù)接口定義規(guī)范定義，其中中間的幾個(gè)元素（斜體標(biāo)注）為擴(kuò)展字段，主要作用是解決各系統(tǒng)對(duì)報(bào)文頭信息的特殊要求。BODY標(biāo)簽中的字段為業(yè)務(wù)字段，具體的結(jié)構(gòu)和內(nèi)容由服務(wù)接口定義。請(qǐng)求報(bào)文固定字段中文名稱英文名稱必填備注交易流水號(hào)SEQ_NON交易流水交易代碼SERVICE_IDY服務(wù)交易代碼渠道代號(hào)CHANNEL_IDY請(qǐng)求渠道號(hào)機(jī)構(gòu)號(hào)BANK_CODEY請(qǐng)求機(jī)構(gòu)號(hào)請(qǐng)求日期TRAN_DATEY格式Y(jié)YYYMMDD，如20110810請(qǐng)求時(shí)間TRAN_TIMEY格式HHMMSSNNN，如092031218擴(kuò)展信息EXT_HEADN擴(kuò)展信息，特殊需要的時(shí)候

24、添加，由ESB做特殊處理示例<Transaction> <HEAD> <SEQ_NO>101000059173</SEQ_NO> <SERVICE_ID>0202</SERVICE_ID> <CHANNEL_ID>ECIF</CHANNEL_ID> <BANK_CODE>9957</BANK_CODE> <USER_ID>99957018</USER_ID> <TRAN_DATE>20111108</TRAN_DATE> <

25、;TRAN_TIME>152859843</TRAN_TIME> <EXT_HEAD> <EXT_PIN/> </EXT_HEAD> </HEAD> <BODY> <KEHHAO>1025919289</KEHHAO> </BODY> </Transaction>響應(yīng)報(bào)文固定字段中文名稱英文名稱必填備注交易流水號(hào)SEQ_NON交易流水交易代碼SERVICE_IDN交易代碼機(jī)構(gòu)號(hào)BANK_CODEN請(qǐng)求操作員所屬機(jī)構(gòu)號(hào)響應(yīng)日期TRAN_DATEY格式Y(jié)YYYMMDD，如2

26、0110810響應(yīng)時(shí)間TRAN_TIMEY格式HHMMSSNNN，如092031218交易狀態(tài)TRAN_STATUSYCOMPLETE表示成功，F(xiàn)AIL表示失敗擴(kuò)展信息EXT_HEADN公共擴(kuò)展信息失敗碼ERROR_CODEN交易失敗時(shí)填寫失敗描述ERROR_MSGN交易失敗時(shí)填寫交易返回碼RET_CODEN交易成功，同時(shí)需要返回響應(yīng)碼時(shí)，可填寫交易返回信息描述RET_MSGN交易成功，同時(shí)需要返回響應(yīng)碼時(shí)，可填寫示例<Transaction><HEAD><SEQ_NO>101000059173</SEQ_NO><SERVICE_ID>

27、;0202</SERVICE_ID><BANK_CODE>9957</BANK_CODE><TRAN_DATE>20111108</TRAN_DATE><TRAN_TIME>152859843</TRAN_TIME><TRAN_STATUS>COMPLETE</TRAN_STATUS><EXT_HEAD /><ERROR_CODE></ERROR_CODE><ERROR_MSG></ERROR_MSG><RET_CODE&

28、gt;</RET_CODE><RET_MSG></RET_MSG></HEAD><BODY></BODY></Transaction>第2章 接口規(guī)范接口規(guī)范是對(duì)服務(wù)報(bào)文元素（SOAP體中的元素）的定義和說明，為了便于查閱，接口定義文件由Excel文件編寫。一個(gè)服務(wù)代表一組相關(guān)操作的集合，一個(gè)服務(wù)包含多個(gè)操作，服務(wù)操作包含如下內(nèi)容：2.1 服務(wù)操作定義Ø 操作IDØ 操作名稱Ø 操作描述Ø 所屬的Web-Service的EndPoint URI原子服務(wù)定義方式為：應(yīng)用路徑/表名