ESB-服务规范

1、南京银行企业服务总线服务接口规范版本：v1.0目录第1章服务规范31.1基本规范31.2SOAP格式规范31.3报文总体组成4固定字段5扩展字段5请求报文6响应报文7出错报文81.4XML格式规范9请求报文10响应报文11第2章接口规范122.1服务操作定义122.2消息定义132.3字段定义132.5命名空间定义14第1章 服务规范1.1 基本规范Ø 消息格式：SOAPØ SOAP绑定模式：document/literalØ 字符编码：UTF-81.2 SOAP格式规范先看一个SOAP报文示例：<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消息的根元素是信封，信封报文主要由报文头（Header）和报文本（Bo

5、dy）构成，ESB的Web-Service将不使用Header，服务调用者可以忽略对Header的关注。因此，ESB的有效载荷在SOAP的Body内，每个Body都只有一个元素（为了便于描述，我们称它为ESB报文元素），这个元素的内部的XML（innerXML）即为要关注的实际报文。如果要了解ESB的接口规格只需简单了解ESB报文元素即可。接口文档的定义，也是针对ESB报文元素进行定义的。上例中的报文元素为：<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>该报文本中，最上面几个元素（黑体标注）为固定字段，所有服务报文都有这些字段。固定字段之后是可变字段，可变字段对于每个服务来说都是不一样的，具体规格由服务接口定义规范定义，其中中间的几个元素（斜体标注）为扩展字段，

8、主要作用是解决各系统对报文公共头信息的特殊要求。1.3 报文总体组成报文体字段由三部分组成：Ø 固定字段：每个服务都具备的字段，用来描述和标识请求与响应报文。Ø 扩展字段：由于固定字段不能保证满足所有交易的请求与响应信息，各系统可以根据需要对报文进行扩展。Ø 服务相关字段：每个服务的请求与响应字段，即业务字段。固定字段固定字段是服务的元数据类型，在模式文件esb.xsd文件中定义，包含了交易所用到的头信息内容，所有通过ESB发布的WebService服务，必须继承固定字段。ESB固定字段定义文件：扩展字段扩展字段是为了满足服务提供者的请求报文和响应报文中特殊的报文

9、头信息而设定的。各业务系统可以根据需要定制扩展字段模式文件，并包含固定字段模式文件。需要注意的是，扩展字段模式文件中的命名空间必须保持与固定字段模式文件中的命名空间一致。建议一个服务提供者的扩展字段模式文件只定义一个。扩展字段模式文件定义示例：<schema targetNamespace=" elementFormDefault="qualified" xmlns="/2001/XMLSchema" xmlns:esb="<!- 导入ESB报文头定义文件 -><include

10、schemaLocation="././Common/Schema/esb.xsd"/><!- ECIF系统请求扩展头 -><complexType name="ECIFRequestBase"><complexContent><extension base="esb:RequestBase"><sequence><!- 扩展字段定义部分 -><!- 客户类型 01：表示个人客户信息；02：表示公司客户信息；00：ECIF系统预留； -><

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>请求报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水交易号SERVICE_IDN服务交易编号，细粒度交易无需填写渠道代号CHANNEL_IDY请求渠道号机构号BANK_CODEY请求机构号操作员USER_IDY请求操作员号授权操作员AUTH_IDN授权操作员号请求日期TRAN_DATEY格式YYYYMMDD，如20110810请求时间TRAN_TIMEY格式HHMMSSNNN，如092031218认证信息

13、AUTH_CONTEXTN认证信息，暂不使用示例<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>响应报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水服务号SERVICE_IDN即交易号，对于细粒度服务不需要填写机构号BANK_CODEN请求操作员所属机构号响应日期TRAN_DATEY格式YYYYMMDD，如20110810响应时间TRAN_TIMEY格式HHMMSSNNN，如092031218交易状态TRAN_STATUSYCOMPLETE表示成功，FAIL表示失败失败码ERROR_CODEN交易失败时填写失败描述ERROR_MSGN交易失败时填写交易返回码RET_CODEN交易成功，同时需要返回响应码时，可

16、填写交易返回信息描述RET_MSGN交易成功，同时需要返回响应码时，可填写示例<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>出错报文ESB系统内部错误，全部通过SOAP Fault返回出错报文，包含以下信息

18、：Faultcode：错误码Faultstring：错误信息描述服务调用者可以通过捕获SOAPFaultException，获取错误信息。返回出错报文<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出错报文<

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格式规范先看一个XML报文示例：<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>该报文本中，HEAD标签中上面几个元素（黑体标注）为固定字段，所有服务报文都有这些字段。固定字段之后是可扩展字段，可

23、扩展字段对于每个服务来说都是不一样的，具体规格由服务接口定义规范定义，其中中间的几个元素（斜体标注）为扩展字段，主要作用是解决各系统对报文头信息的特殊要求。BODY标签中的字段为业务字段，具体的结构和内容由服务接口定义。请求报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水交易代码SERVICE_IDY服务交易代码渠道代号CHANNEL_IDY请求渠道号机构号BANK_CODEY请求机构号请求日期TRAN_DATEY格式YYYYMMDD，如20110810请求时间TRAN_TIMEY格式HHMMSSNNN，如092031218扩展信息EXT_HEADN扩展信息，特殊需要的时候

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>响应报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水交易代码SERVICE_IDN交易代码机构号BANK_CODEN请求操作员所属机构号响应日期TRAN_DATEY格式YYYYMMDD，如2

26、0110810响应时间TRAN_TIMEY格式HHMMSSNNN，如092031218交易状态TRAN_STATUSYCOMPLETE表示成功，FAIL表示失败扩展信息EXT_HEADN公共扩展信息失败码ERROR_CODEN交易失败时填写失败描述ERROR_MSGN交易失败时填写交易返回码RET_CODEN交易成功，同时需要返回响应码时，可填写交易返回信息描述RET_MSGN交易成功，同时需要返回响应码时，可填写示例<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章 接口规范接口规范是对服务报文元素（SOAP体中的元素）的定义和说明，为了便于查阅，接口定义文件由Excel文件编写。一个服务代表一组相关操作的集合，一个服务包含多个操作，服务操作包含如下内容：2.1 服务操作定义Ø 操作IDØ 操作名称Ø 操作描述Ø 所属的Web-Service的EndPoint URI原子服务定义方式为：应用路径/表名