ESB服务规范标准详.docx
《ESB服务规范标准详.docx》由会员分享,可在线阅读,更多相关《ESB服务规范标准详.docx(14页珍藏版)》请在冰豆网上搜索。
ESB服务规范标准详
银行企业效劳总线效劳接口规
版本:
v1.0
第1章效劳规
1.1根本规
Ø消息格式:
SOAP
ØSOAP绑定模式:
document/literal
Ø字符编码:
UTF-8
1.2SOAP格式规
先看一个SOAP报文示例:
Envelopexmlns:
soapenv="schemas.xmlsoap.org/soap/envelope/">
Headerxmlns:
soap="schemas.xmlsoap.org/soap/envelope/">
Header>
Body>
PersonInfoListRequestxmlns:
tns="
0
A6002
2003
1001000
9999
20080929
095050
1
1
10
9
011
weikai
PersonInfoListRequest>
Body>
Envelope>
SOAP消息的根元素是信封,信封报文主要由报文头〔Header〕和报文本〔Body〕构成,ESB的Web-Service将不使用Header,效劳调用者可以忽略对Header的关注。
因此,ESB的有效载荷在SOAP的Body,每个Body都只有一个元素〔为了便于描述,我们称它为ESB报文元素〕,这个元素的部的XML〔innerXML〕即为要关注的实际报文。
如果要了解ESB的接口规格只需简单了解ESB报文元素即可。
接口文档的定义,也是针对ESB报文元素进展定义的。
上例中的报文元素为:
PersonInfoListRequestxmlns:
tns="
0
2003
1001000
9999
20080929
095050
1
1
10
9
011
weikai
PersonInfoListRequest>
该报文本中,最上面几个元素〔黑体标注〕为固定字段,所有效劳报文都有这些字段。
固定字段之后是可变字段,可变字段对于每个效劳来说都是不一样的,具体规格由效劳接口定义规定义,其中中间的几个元素〔斜体标注〕为扩展字段,主要作用是解决各系统对报文公共头信息的特殊要求。
1.3报文总体组成
报文体字段由三局部组成:
Ø固定字段:
每个效劳都具备的字段,用来描述和标识请求与响应报文。
Ø扩展字段:
由于固定字段不能保证满足所有交易的请求与响应信息,各系统可以根据需要对报文进展扩展。
Ø效劳相关字段:
每个效劳的请求与响应字段,即业务字段。
固定字段
固定字段是效劳的元数据类型,在模式文件esb.xsd文件中定义,包含了交易所用到的头信息容,所有通过ESB发布的WebService效劳,必须继承固定字段。
ESB固定字段定义文件:
扩展字段
扩展字段是为了满足效劳提供者的请求报文和响应报文中特殊的报文头信息而设定的。
各业务系统可以根据需要定制扩展字段模式文件,并包含固定字段模式文件。
需要注意的是,扩展字段模式文件中的命名空间必须保持与固定字段模式文件中的命名空间一致。
建议一个效劳提供者的扩展字段模式文件只定义一个。
扩展字段模式文件定义示例:
elementFormDefault="qualified"
xmlns=".w3.org/2001/XMLSchema"
xmlns:
esb="
--导入ESB报文头定义文件-->
--ECIF系统请求扩展头-->
RequestBase">
--扩展字段定义局部-->
--客户类型01:
表示个人客户信息;
02:
表示公司客户信息;
00:
ECIF系统预留;-->
……
请求报文
固定字段
中文名称
英文名称
必填
备注
交易流水号
SEQ_NO
N
交易流水
交易号
SERVICE_ID
N
效劳交易编号,细粒度交易无需填写
渠道代号
CHANNEL_ID
Y
请求渠道号
机构号
BANK_CODE
Y
请求机构号
操作员
USER_ID
Y
请求操作员号
授权操作员
AUTH_ID
N
授权操作员号
请求日期
TRAN_DATE
Y
格式YYYYMMDD,如20110810
请求时间
TRAN_TIME
Y
格式HHMMSSNNN,如092031218
认证信息
AUTH_CONTEXT
N
认证信息,暂不使用
示例
PersonInfoListRequest
xmlns:
tns="
0
2003
1001000
9999
20080929
095050
1
1
10
9
011
weikai
PersonInfoListRequest>
响应报文
固定字段
中文名称
英文名称
必填
备注
交易流水号
SEQ_NO
N
交易流水
效劳号
SERVICE_ID
N
即交易号,对于细粒度效劳不需要填写
机构号
BANK_CODE
N
请求操作员所属机构号
响应日期
TRAN_DATE
Y
格式YYYYMMDD,如20110810
响应时间
TRAN_TIME
Y
格式HHMMSSNNN,如092031218
交易状态
TRAN_STATUS
Y
COMPLETE表示成功,FAIL表示失败
失败码
ERROR_CODE
N
交易失败时填写
失败描述
ERROR_MSG
N
交易失败时填写
交易返回码
RET_CODE
N
交易成功,同时需要返回响应码时,可填写
交易返回信息描述
RET_MSG
N
交易成功,同时需要返回响应码时,可填写
示例
PersonListResponse
xmlns:
ser="
0000
string
20080929
095050
COMPLETE
st
string
string
飞
ZhangFei
PersonListResponse>
出错报文
ESB系统部错误,全部通过SOAPFault返回出错报文,包含以下信息:
Faultcode:
错误码
Faultstring:
错误信息描述
效劳调用者可以通过捕获SOAPFaultException,获取错误信息。
返回出错报文
PersonListResponse
xmlns:
ser="
0000
string
20080929
095050
FAIL
CIF5557
客户不存在
st
string
string
PersonListResponse>
SOAP出错报文
Envelopexmlns:
soapenv="schemas.xmlsoap.org/soap/envelope/">
Header/>
Body>
Faultxmlns:
fault="example.">
E001
thefaultstring
Fault>
Body>
Envelope>
1.4XML格式规
先看一个XML报文示例:
3
0202
ECIF
9957
99957018
20111108
152859843
1025919289
该报文本中,HEAD标签中上面几个元素〔黑体标注〕为固定字段,所有效劳报文都有这些字段。
固定字段之后是可扩展字段,可扩展字段对于每个效劳来说都是不一样的,具体规格由效劳接口定义规定义,其中中间的几个元素〔斜体标注〕为扩展字段,主要作用是解决各系统对报文头信息的特殊要求。
BODY标签中的字段为业务字段,具体的结构和容由效劳接口定义。
请求报文
固定字段
中文名称
英文名称
必填
备注
交易流水号
SEQ_NO
N
交易流水
交易代码
SERVICE_ID
Y
效劳交易代码
渠道代号
CHANNEL_ID
Y
请求渠道号
机构号
BANK_CODE
Y
请求机构号
请求日期
TRAN_DATE
Y
格式YYYYMMDD,如20110810
请求时间
TRAN_TIME
Y
格式HHMMSSNNN,如092031218
扩展信息
EXT_HEAD
N
扩展信息,特殊需要的时候添加,由ESB做特殊处理
示例
3
0202
ECIF
9957
99957018
20111108
152859843
1025919289
响应报文
固定字段
中文名称
英文名称
必填
备注
交易流水号
SEQ_NO
N
交易流水
交易代码
SERVICE_ID
N
交易代码
机构号
BANK_CODE
N
请求操作员所属机构号
响应日期
TRAN_DATE
Y
格式YYYYMMDD,如20110810
响应时间
TRAN_TIME
Y
格式HHMMSSNNN,如092031218
交易状态
TRAN_STATUS
Y
COMPLETE表示成功,FAIL表示失败
扩展信息
EXT_HEAD
N
公共扩展信息
失败码
ERROR_CODE
N
交易失败时填写
失败描述
ERROR_MSG
N
交易失败时填写
交易返回码
RET_CODE
N
交易成功,同时需要返回响应码时,可填写
交易返回信息描述
RET_MSG
N
交易成功,同时需要返回响应码时,可填写
示例
3
0202
9957
20111108
152859843
COMPLETE
第2章接口规
接口规是对效劳报文元素〔SOAP体中的元素〕的定义和说明,为了便于查阅,接口定义文件由Excel文件编写。
一个效劳代表一组相关操作的集合,一个效劳包含多个操作,效劳操作包含如下容:
2.1效劳操作定义
Ø操作ID
Ø操作名称
Ø操作描述
Ø所属的Web-Service的EndPointURI
原子效劳定义方式为:
应用路径/表名+Service
例如对公客户根本信息维护效劳:
ip:
port/EsbService/PSNBaseInfoService
ØWeb-Service操作名称(OperationName)
查询客户清单操作:
queryPersonList
Ø输入消息定义
操作输入消息名:
PersonListRequest
类型名定义:
业务信息〔首字母大写,词组组合的首字母大写〕+Request.
Ø输出消息定义
操作输出消息名:
PersonListResponse
类型名定义:
业务信息〔首字母大写,词组组合的首字母大写〕+Response
Ø相关完成代码备注
2.2消息定义
消息包含如下定义〔不需要列出固定字段〕:
Ø消息名称,即报文元素的名称。
Ø报文元素的名命空间
Ø各个子元素〔报文字段〕说明
2.3字段定义
字段说明包含如下容
Ø字段名称:
原那么上是带有业务含义的字段名称,为了便于Java系统使用,可以采用java对象字段的书写习惯,小写开场、单词间隔用大写字母,同时为了增加ESBWebService易维护性,对于非WebService效劳的WebService效劳化,尽量保持与原字段名称一致。
Ø类型:
可以采用XML-Schema的类型。
Ø长度:
如果是字符串类型,应说明支持的最大长度。
不写,为不限制长度。
Ø是否允许空值。
Ø格式:
对于日期类型,应该说明日期的格式。
其它类型如果有特殊格式要求,应在此标注。
Ø备注:
对字段的附加说明。
2.5命名空间定义
ØSchema命名空间定义:
⏹效劳对应的数据类型命名空间:
ØWSDL命名空间定义:
Service/
ØESB公用信息命名空间定义:
Ø扩展信息命名空间定义:
与ESB公用信息命名空间保持一致,即:
ØSchema文件存放路径与效劳绑定定义:
Schema文件跟wsdl放同一个路径下,文件名以效劳名〔首字母大写,词组组合的首字母大写〕命名。
效劳所绑定的效劳名以效劳名〔首字母大写,词组组合的首字母大写〕+Service命名