完整的接口解决方案说明书

1、文档编号T-JKJS文档版本：0.01/ 工程编号： XX-DX- PECS«xx电信工程外部协作系统?Project Exterior CooperationSystem施工单位接口技术解决方案编写人：南疯日期：2006-10-30审核人：日期：批准人：日期：XXXXX漏息科技股份地址：XXXXXXX由惭：XXXXXX ：XXXXXXXX ：XXXXXX网站：XXXXXXXXX修改记录(Revision Chart )版本号批准人修改人/I1修10.01南疯/2006-10-300.02详细修改记录:1引言1.1 编写目的本文档为XX电信工程外部协作系统以下简称外协系统与电信工程施

2、工单位内部系统 以 下简称施工系统接口技术解决方案,以此作为外协系统与施工系统实施接口的技术方案依据和 工程设计标准.1.2 覆盖范围XX电信工程外部协作系统工程组施工系统接口开发技术组1.3预期读者与阅读建议XX电信企业信息化部XX 电信工程建设部XXXX公司开发人员施工系统开发人员1.4 文档约定粗体正文表示强调内容红色正文表示未完成或需要今后考虑的内容蓝色正文表示待讨论内容1.5术语与缩略语术语、缩略语定 义外协系统XX电信工程外部协作系统施工系统电信工程施工单位内部系统PECSXX电信程外部协作集统英文简称|1.6 参考文献(XXXX)2 概述建设XX电信工程外部协作系统的目标, 是在

3、工程工程的治理、建设、使用和实施单位之间搭 建起数据交换和协同工作的信息平台,延伸与拓展工程建设治理信息化的应用范围,实现通信工程建设过程的信息化治理, 促进工程工程的治理部门、 建设部门、实施部门和使用部门之间业务 流程协调有序地开展,实现工程工程设计、施工、监理治理功能,将相关的设计、施工、监理单 位纳入到工程建设治理中, 完善工程工程建设过程治理体系, 通过信息化推动治理的标准化, 在 信息化的应用过程中不断探索市场环境下工程建设治理的新思路和新方法.根据工程部业务工作的实际情况, 工程首先满足工程建设治理中应用最广泛、问题最突出的根本工程功能需求包括：?建立工程外部协作系统与 MSS等

4、系统的接口；?建立设计协作效劳、监理协作效劳、施工协作效劳模块,为邮电设计院、 监理公司和电信工程公司提供工程部所需的协作效劳,保证工程建设实施流程的开展；?在建立工程协作效劳模块的根底上,建立工程外部协作系统与邮电设计院、 监理公司、电信工程公司信息系统的接口, 实现工程部与三家实施单位的信息交互与业务协作;本技术解决方案就是针对实现工程建设部与三家实施单位信息交互与业务协作接口中施工 单位接口的技术解决方案的组成局部.在接口的调用过程中,存在施工系统调用外协系统接口的情况,这时候,施工系统作为客 户端,外协系统作为效劳端；也存在外协系统调用施工系统的情况,这时候,外协系统作为客 户端,施工

5、系统作为效劳端.本方案中,除了特殊另外说明外,不考虑外协系统和施工系统角 色换位的问题.如果一方发起了调用,那么它就是客户端,另一方就是效劳端.反之亦然.4 接口方式工程外协系统与施工系统之间的接口采用Web Service接口形式来进行业务数据的交互.接口数据传输采用XML数据交换格式,utf-8编码.在外协系统中提供 Web Service的API接口.提供由施工系统调用获得信息；并且提供 施工系统提交信息的API接口.同样,在施工系统中提供 Web Service的API接口.提供由外协系统提交信息的 API接 口.考虑到工程外协中的数据信息不仅包括了XX电信工程公司的数据而且还包含了其

6、他的施工单位的数据信息.而这些单位也各有其各自工程应用系统.这样,外协系统对各个施 工单位系统所提供的接口 API及其参数信息、格式均是统一的.同时,也要求各个施工单 位所提供的接口 API及其参数、格式等也必须要求统一.外协系统与施工系统属于一对多 的关系.外协系统要求能够有目的,信息有过滤的把业务信息通过接口正确的发送给相应施工系 统接口.非相关的信息不要发送给对应的施工系统.施工系统建立用户映像对照表、字典对照表、单位对照表等数据映像,传递给外协的数 据使用的是映像中转换后的外协系统能够识别数据；同时,接收到的数据也根据对照表转 换成各自能够解释的数据格式.数据初始化的时候,由施工系统主

7、动调用外协系统的接口,以获得用户信息、字典信息、单位信息、工程信息等根底信息.以后,一旦发生数据的变动,由外协系统主动往施工系 统发送信息.外协系统不主动请求施工系统获得数据,但是外协系统会主动请求施工系统发送数据.施工系统主动请求外协系统获得数据,也会主动请求外协系统发送数据O4 接口平安 4 .1 接口认证调用认证：虽然接口双方都是存在于电信内部网络中,但是,仍不能排除接口效劳被攻击、 恶意调用以及非法调用等.所以,从接口调用上,必须考虑调用的认证平安问题.本方案中的接口,在客户端调用效劳端的时候,必须经过调用身份认证.考虑施工系统的开发平台的多样性,但同时接口效劳运行平台都是 Windo

8、ws的情况,本方案采用 Windows 平安身份认证的方式.即在访问接口所在的效劳的时候,都必须进行资格审查使用 Credentials 发送认证信息.另外,接口采用SOA嗣、议,因此在接口配置上面需要屏蔽HTTPGET和HTTPPOST其他协议.在接口中审核并进行日志的记录.使用最低权限的进程帐户运行 Web效劳通过Machine.config 中的<processModel>元素来配置.接口不支持动态生成WSDL因此作为效劳端,应该禁止文档协议.在效劳端禁用跟踪,禁用调式编译业务用户认证：由于接口涉及电信工程中的各个不同的业务,有获取字典、获得工程信息、发送开工报告等,所以,建

9、立一套业务的用户认证机制是必须的.不同的用户,所具备有的授权不一样,所能执行的业务也不一样.同时,业务用户认证中的用户信息也是记录接口日志中的重要组成局部.本方案采用的是在接口信息中包含业务认证用户信息的方式来进行认证.效劳端在收到请求的时候,应先验证业务的授权用户, 如果该业务用户没有执行当前业务的权限, 应终止 业务的执行,并给出非法用户的警告信息反应回客户端.一般情况下,业务认证的用户是系统中的用户.业务认证其实就是应用系统认证的组成局部.业务认证的用户信息经过加密之后包含在要发送的信息XML体中,即在发送的信息中包含业务用户的信息参见下面的数据格式说明.4 .2数据平安数据的平安表现为

10、如何保证数据在网络传输过程中不会被截获并被解析其中的内容而 引起信息泄露与如何保证数据在传输的过程中的数据的完整性两个方面.WebService采用XML数据格式来传输信息.所以,无论是发送数据还是返回结果,都 要求采用对XML数据加密之后来传输.至于采用何种方式的加密技术,本方案为了保密,只能在开发的时候由开发人员口头告知.涉及到加密技术就要涉及到加密的密钥问题.目前, 外协系统和施工系统接口上有很多种类型的业务,到底是每种类型的业务采用不同的密钥, 还是按分组来采用同一种密钥的方式,还是所有的业务全部采用同一种的密钥的方式, 根据需求各有不同的选择.本方案采用的是最后一种的方式.密钥的发布

11、由作为效劳方来发布, 由客户端获取.密钥的发布方式待定.为了保证数据的完整性,首先：方案采用数据签名SOAPSecurity Extensions: Digital Signature .利用 XML的数字签名XML Digital Signature syntax XML-Signature 对 SOAP®行扩展,在SOAP勺头元素中定义签名属性<SOAP-SEC:Signature> 来实现.其次：限制并验证 Web方法输入的类型、 长度、格式和范围,验证对XML输入数据的验证是基于 已协商的架构等.5 事务处理事务是一组相关的任务,作为独立于其他任务的独立单元成功提

12、交或失败中止C分布式事务是影响多个资源的事务.要提交分布式事务,所有参与者都必须保证对数据的任何更改是永久的.不管系统崩溃或是发生其他无法预料的事件,更改都必须是持久的. 即使只有一个参与者无法保证这一点,整个事务也将失败,在事务范围内对数据的任何更改均将回滚.外协系统和施工系统是处于网络之上的两个分布式接口,使用的是分布式事务.要启用分布式事务,可能需要通过网络启用 MS DTC考虑外协平台和施工平台都是运行在Windows上,以便在使用应用了最新的Service Pack的较新操作系统例如 Windows XP或Windows 2003时使用分布式事务. 如果启用了 Windows防火墙W

13、indows XPService Pack 2的默认设置,必须允许 MS DTC效劳使用网络或翻开 MS DTC端口.接口中的效劳端和客户端的环境事务始终相同,客户端创立的事务上下文并应用对于服务端的当前的事务,以便对于该事务上下文是当前的.这样的事务会造成性能损失,由于可能需要继承原来的上下文,但是,这样的事务保证了在数据库操作的时候信息的完整性.接口中事务的发起总是由客户端发起的,并负责事务的提交和回滚等限制.6 性能考虑在接口设计的时候就应该考虑性能上面的问题,不要在事后再参加性能.同时,在工程的开发过程要反复进行测试,可以从机器的吞吐量和响应时间两个根本的指标来衡量接口的 性能.接口上

14、面的性能考虑主要从下面几个方面来优化：使用一次连接,屡次调用,优化连接资源.对于并行的接口调用使用异步的调用方式.优化线程池减少竞争.考虑使用XML压缩.如果不需要返回,考虑使用单工通讯的方式.适当的设置如果有代理代理超时,页面超时,WebService超时.设计大块头"的接口减少往返.基于消息的编程而不是远程过程调用RPC.使用XML字串作为参数.尽量使用原始数据类型参数.防止在调用之间维护效劳器状态.考虑为复杂的WebMethod提供输入校验.考虑对WebMethod的结果使用缓存.选择适用的大数据包传送方式.防止调用本地的 WebService.7 容错处理客户端向效劳端发送数

15、据, 效劳端解析数据,反应信息给客户端,这中间的环节只要某 一个环节出现问题,都会造成接口的失败.根据失败产生的环节分类,我们可以从三个方面 来处理接口的失败.网络连接失败：在调用接口的时候,由于网络不通,造成数据不能正常传输.这样,客户端应该能够记录发送的日志,根据一定的时间间隔重试发送.本方案定为重试发送20次,每次时间间隔2小时.如果一直发生网络不通的情况,该发送日 志被保存下来,待后手工发送.所以,客户端系统应该实现手工发送数据的功能.反应错误信息：效劳端在解析数据包,执行数据包业务的时候,可能会发生异常.所以,效劳端应当能够捕捉异常信息,比方“非法 XML格式等,然后反应给 客户端.

16、客户端在接受到这类的错误信息之后, 应当进行日志记录,能够自动或手 工分析异常的信息.网络连接正常,但是无信息反应：这种情况下,一般是效劳端出现了异常,但 是又没有捕捉到的情况下发生.这种情况下,客户端把这种错误当作“网络连接失 败来处理.效劳端应能够实现相同数据包重新发送过来的处理机制.8 数据格式在Web Service的调用过程中,无论是外协系统还是施工系统,都有发送数据和接收数据 的要求,也即双方系统同时作为客户端又作为效劳端.我们统称这些传递的数据为报文.客户端发送报文,属于调用；效劳端接收报文,属于被调用.客户端和效劳端互相之间通讯的请求报文和结果报文遵循XMLM式.客户端发送请求

17、报文,效劳器解析调用报文,执行报文中所在接口对应的效劳功能.生成结果报文,以xml格式页返回给请求者.请求者拿到结果报文,进行解析,然后再进行相应的处理.8.1 约定报文中所有的字典信息比方性别 1-男,2-女,都以代码的值1或者2来传递.施 工单位向外协系统发送的报文中的代码都需要转换成外协的代码,外协系统向施工系统发 送的报文中的代码无需转换.报文中的其他数据类型,比方货币、RowID,自定义对象类型等,根据需要转换成文本、数值或二进制最终转换成 Base6狞符的数据类型.报文中数值信息,转换成文本,如:<ItemCount>50</ItemCount><Va

18、lueSum>12368.36</ValueSum>报文中数值不支持科学计数的方式.报文中数值的单位使用国标的单位,比方货币使用“元,长度使用“米等.无国标的单位以约定为准.报文中的日期信息,转换成 YYYYMMDD HHmmsS格式24小时制.如果是空日期, 那么转换成空文本.报文中的true和false数据类型,转换成0表示false、1 表示true 报文中的二进制数据,转换成 Base6狞符方式发送.报文中的记录集,放在 Records标签中；报文中一条记录,放在 Records标签中.报文中如果存在多条记录,那么在 Records标签中就包含多个的Record标签.

19、如果报文中仅有一条记录,贝U Records标签中只包含一个Record标签.如果没有记录,那么仅仅 包含一个Records标签,没有Record标签.如果返回结果数据集非常多,在性能考虑和数据量冲突的情况下,可以使用分页返回数据集的方式分批返回数据每次返回最多100条记录.效劳端提供分批结果返回的功能.至于如何使用分页查询的功能,参见下面的XML框架说明.8.2施工系统向外协系统发送请求如何请求查询一个业务数据如何新增一条记录,新增之后如何点到记录的键值如何修改一条记录如何删除一条记录文档如何上传一条记录中一个FilelD的字段如何上传多个文件如何在一条记录中补充上传文档如何在一条记录中删除

20、一个文档如何获得文档的根本信息如何获得文档的所有兄弟信息如何获得文档的所有父亲信息如何下载一个文档针对这些问题,接口方案的解决方法如下：8.2.1请求查询一个业务数据施工系统针对外协系统发送的业务数据查询请求根据业务类型有很多种.为了简化接口,而不是在接口上进行业务操作,所以,外协系统将施工系统发起的数据查询请求看作是数据下载的一种方式, 而不为了复杂的业务查询请求提供复杂的条件解析.外协系统提供的数据查询接口是从数据下载和数据延期性来考虑的.为了满足数据的下载,外协系统提供了根据某一个表的主键来下载数据和根据记录的变更时间范围来下载数据的两种方式查询 请求.请求报文：I ? xml vers

21、ion="1.0" encoding="utf-8" ?>< XmlData>< Userlnfo>< User > ZhangSan </ User >< Password > 123456 </ Password ></ Userlnfo >< Description >< RowID > 0</ RowID >< KeyValue > 123 </ KeyValue >< QueryBeginT

22、ime > 20061018153000</ QueryBeginTime >< QueryEndTime > 20061019153000 </ QueryEndTime ></ Description ></ XmlData >响应报文：<? xml version="1.0" encoding="utf-8" ?>< XmlData >< Description >< RowID > 100 </ RowID ></

23、Description >< Records >< Record >< Field1 > Value1 </ Field1 >< Field2 > Value2 </ Field2 >< Field3 > Value3 </ Field3 >< Field4 > Value4 </ Field4 ></ Record >< Record >< Field1 > Value1 </ Field1 >< Field2 &

24、gt; Value2 </ Field2 >< Field3 > Value3 </ Field3 >< Field4 > Value4 </ Field4 ></ Record >< Record >< Field1 > Value1 </ Field1 >< Field2 > Value2 </ Field2 >< Field3 > Value3 </ Field3 >< Field4 > Value4 </ Fiel

25、d4 ></ Record ></ Records ></ XmlData >报文说明：|标签名说明/<XmlData>报文数据主体|<Description >报文头部信息/|<Records>记录集合<Record >一行记录<UserInfo >业务认证的用户信息/|<User>业务用户登录名<PassWord>业务用户验证口令一7<RowID>第一次请求的时候,客户端RowID发送0,表示从第0条记录开发返回.效劳端根据条件查询,发现结果超过100条

26、记录,那么在返回的结果中,RowID 的值为99,表示效劳端当前的记录位置处在第 100条的位置上,后面还会 有剩余的记录.客户端检查返回的结果,如果发现RowID大于0,那么继续发送请求进行查询.但是,客户端第二次发送请求继续查询的时候,RowID的值要赋值为第一次返回的值,即RowID=99效劳端第二次收到请求的时候,发现RowID是99,那么从第100条返回结果.以此类推循环调用,直到服 务端到达记录的末尾,这时候,效劳端在返回的结果中 RowID=0.客户端发 现效劳端RowID=0终止循环调用.字典、用户信息、单位信息,由于返回的字段比拟少,不受100记录返回的限制.一次调用,就返回

27、全部的结果.<KeyValue >查询时主键的值.这个KeyValue和下面的 QueryBeginTimeQueryEndTime是互斥的.如果在请求的时候提供了主 键的值,表示客户端要求效劳器根据主键的值查询一条记录.如果客户端 提供了主键的值,那么效劳端将忽略QueryBeginTimeQueryEndTime中的 值.字典、用户信息、单位信息,由于没有查询时间范围,、所以KeyValue 即表示字典类型.|<QueryBeginTime >查询时时间段范围.QueryBeginTime 是起始时间,QueryEndTime<QueryEndTime>

28、是结束时间.表示客户端要求效劳端查询在这个时间范围之内所有变更过 的记录包括新增、修改、删除.在外协中,一条记却增的时候,它的创立时间和最后修改时间是一、 样的,以后修改记录的时候,创立时间不变,改变的仅仅是最后修改时间. 同时,夕卜协系统中删除记录仅仅在“记录是否删除字段中标记“1,并不是真正的物理删除记录.这里的时间指的是记录变更的时间,不是记录中的某个业务时间. 如果用户需要根据业务时间来查询数据,那么施工系统把外协系统的数据获取 到本地进行保存,在施工系统中提供根据业务时间查询的功能.QueryBeginTimeQueryEndTime和KeyValue是互斥的.如果客户 端需要根据时

29、间范围来查询,那么必须 KeyValue空.<Field1 >一行记录中的英文字段名称.实际中,这些标签都是字典的英文名.字段 <Field2 >的标签全部是大写.<Field3 ><Field4 >具体的字段名称请参见提供的数据模型8.2.1新增一条记录,得到记录的键值为了简化数据模型的处理,本方案不考虑主从表的并发处理情况.如果存在主从表的数据需要上 传,那么,在一个事务中,施工单位首先先上传主表的记录, 从反应信息中获得主表的主键值. 然后, 把刚刚获得的主表的主键值赋值给从表的对应外键,再上传从表数据,得到从表的主键值.如果不是主从表,而

30、是单表,那么直接上传数据,从反应信息中得到主键值.这种情况的优点是：数据和表相关,施工单位可以灵活的限制表之间的关系；同时,数据包中的报文比拟简单,容易解析；接口上面比拟清楚,与业务的耦合比拟低.缺点是：一个业务涉及的主从表不能在同一个报文中这个缺点可以通过施工系统灵活的限制表之间关系来解决；一个业务中可能会使用到两个或两个以上的接口,造成业务完整性上面的别离这种缺点可以通过把业务放在一个事务中来解决；键值的返回：在调用新增接口之后,外协会根据记录的顺序返回外外协中所生成的键值.施工单位获得键值之后,可以在本地表中更新记录的主键值.请求报文：<? xml version="1.

31、0" encoding="utf-8" ?>< XmlData >< UserInfo >< User > ZhangSan </ User >< PassWord > 123456 </ PassWord ></ UserInfo >< Description >< Note > 开工报告 </ Note ></ Description >< Records >< Record >< KeyFie

32、ld ></ KeyField >< NormalField1> Value1</NormalField1>< NormalField2> Value2</NormalField2>< NormalField3> Value3</NormalField3>< NormalField4> Value4</NormalField4></ Record >< Record >< KeyField ></KeyField>< Norma

33、lField1> Value1</NormalField1>< NormalField2> Value2</NormalField2>< NormalField3> Value3</NormalField3>< NormalField4> Value4</NormalField4></ Record ></ Records ></ XmlData >响应报文：<? xml version="1.0" encoding="utf-8&q

34、uot; ?>< XmlData >< Description >< Result >成功</ Result ><!-如果失败,贝U <Result>里面内容是：失败：错误原因-></ Description >< Records >< Record >< KeyField > Value1 </ KeyField ></ Record >< Record >< KeyField > Value2 </ KeyFie

35、ld ></ Record ></ Records ></ XmlData >报文说明:标签名说明<XmlData>报文数据主体<Description >报文头部信息""1<Records>记录集合r<Record>-行记录1<UserInfo >业务认证的用户信息1<User>业务用户登录名<PassWord>业务用户验证口令1<Note>业务的简单描述.比方：开工报告、施工组织方案等请求中的<KeyField >一行记录

36、中的主键字段.在新增的时候,施工系统所给的主键字段内容为空.外协系统中根据主键字段内容为空,认为这是一条新增的记录响应中的<KeyField >一行记录中的主键字段.外协系统返回的主键值.这里的主键值和施工系 统发送的记录的顺序是一一对应的.<Result >反应报文中的保存成功与否信息.如果保存成功,那么信息是“成功如果保存失败,那么信息是“失败：后面是错误的详细信息8.2.3修改一条记录施工系统在修改了一条记录的时候,上传的报文中与新增的报文类似,只是主键的信息不能为空. 外协系统判断主键的信息,如果发现主键的信息不为空,那么认为是修改了一条记录.如果施工系统报 文

37、中主键不为空,而外协系统在数据库对应的表中又没有发现对应的记录,那么自动转换成新增的方式来处理这条记录.外协系统在反应中,还是会把主键返回给施工系统.但是,这种情况下,施工系统可能不再需要 维护这个主键.即使是仅仅修改了一个字段,施工单位还得需要上传全部的字段信息包含被修改的字段给外 协系统.施工系统不是对记录做物理删除,而仅仅是作了逻辑删除,即仅仅在记录的删除标志位上面做了“1的标志.这种情况对记录来说,也是修改的范围.只是需要在Note业务的简单描述中说明“逻 辑删除.即使是逻辑删除记录,施工系统也必须上传全部的字段到外协系统.请求才艮文：<? xml version="1

38、.0" encoding="utf-8" ?>< XmlData >< UserInfo >< User > ZhangSan </ User >< PassWord > 123456 </ PassWord ></ UserInfo >< Description >< Note >停工通知确认</ Note ></ Description >< Records >< Record >< KeyFi

39、eld > KeyValue1 </ KeyField >< NormalField1 > Value1 </ NormalField1 >< NormalField2> Value2</NormalField2>< NormalField3> Value3</NormalField3>< NormalField4> Value4</NormalField4></ Record >< Record >< KeyField >KeyValue2&l

40、t;/KeyField >< NormalField1> Value1</NormalField1>< NormalField2> Value2</NormalField2>< NormalField3> Value3</NormalField3>< NormalField4> Value4</NormalField4></ Record ></ Records ></ XmlData >响应报义：<? xml version="1.0&qu

41、ot; encoding="utf-8" ?>< XmlData >< Description >< Result >成功</ Result ><!-如果失败,贝U <Result>里面内容是：失败：错误原因-></ Description >< Records >< Record >< KeyField > Value1 </ KeyField ></ Record >< Record >< KeyFiel

42、d > Value2 </ KeyField ></ Record ></ Records >报文说明:标签名./'说明<XmlData>,报文数据主体'、1<Description >报文头部信息1<Records>记录集合、1<Record >一行记录<UserInfo >业务认证的用户信息一1<User>业务用户登录名1<PassWord>业务用户验证口令、1<Note>业务的简单描述.比方：开工报告、施工组织方案等 1请求中的<

43、KeyField >一行记录中的主键字段.在修改的时候,施工系统所给的主键字段内容不 能为空.外协系统中根据主键字段内容不为空,认为这是一条修改的记录响应中的<KeyField >一行记录中的主键字段.外协系统返回的主键值.这里的主键值和施工系 统发送的记录的顺序是一一对应的.<Result >反应报文中的保存成功与否信息.如果保存成功,那么信息是“成功如果保存失败,那么信息是“失败：后面是错误的详细信息<NormalField >一行记录中的英文字段名称.实际中,这些标签都是字典的英文名.字段 的标签全部是大写.具体的字段名称请参见提供的数据模型8.

44、2.4删除一条记录这里的删除指的是物理删除.逻辑删除在记录修改的时候已经说明.物理删除是彻底的从数据库中删除一条记录,不能恢复.物理删除的时候,施工系统只要在报文 中提供主键的信息提交,就能够实现.同样的,夕卜协系统在反应的报文中返回成功删除主键的信息,如果其中一条记录不能正常物理删除,那么外协自动回滚所有删除的操作.即一条记录不能删除,那么所有的记录都不能删除.请求报文： <?xml version="1.0" encoding="utf-8" ?><XmlData><UserInfo ><User>Zh

45、angSan</ User><PassWord>123456</ PassWorO</ UserInfo ><Description ><Note>物理删除 </ Note>报文说明：(参见数据修改说明)8.2.5文档上传 /外协系统中,文档的信息是保存在另外的一个表中当中的,所以,许多的业务表,往往存在一个FilelD的主键关联到文档表.在业务表中档,可能有一个FilelD的字段,也可能会有两个或两个以上的FilelD字段关联到文档信息表.、/涉及到文档的地方,往往文档的信息会比拟大,所以,文档的信息不能包含在根底

46、业务数据的报 文当中一起上传.处理的方法是：先上传文档的实体,从反应的信息当中得到生成的文档ID (FilelD ),然后,施工系统在本地记录中的相应字段赋值文档的ID,最后再上传根本业务信息.如果一条记录中包含有两个或两个以上的文档字段,那么施工系统必须依次上传文档获得文档ID之后,赋值,再上传根本业务信息.一个文档报文当中,只能上传一个文档.文档报文如下:<?xml version="1.0" encoding="utf-8"?><XmlData><UserInfo ><User>ZhangSan<

47、;/ User><PassWord>123456</ PassWord></ UserInfo ><Description ></ Description ><Records><Record><ID></ID><FILE_PRJ_ID>123456</ FILE_PRJ_ID><FILE_TYPE401 </ FILE_TYPE><FILE_NAMEM工组织方案.DOG/FILE_NAM><FILE_UNIT>电信工

48、程公司 </FILE_UNIT><FILE_MAN张三 </FILE_MAN><FILE_CREATE_TIM>20061031 153005</ FILE_CREATE_TIME<FILE_AUTHO>R长三 </FILE_AUTHOR<FILE_TITLE>工程 XXX施工组织方案 </FILE_TITLE><KeepMutiFile >1 </ KeepMutiFile ><FileData >/e5asfdfgafa#sdgsdg </FileData &

49、gt;</ Record ></ Records ></XmlData>响应报文:<? xml version="1.0" encoding="utf-8" ?>< XmlData >< Description >< Result >成功</ Result ><!-如果失败,那么返回信息是"失败：错误信息-></ Description >< Records >< Record >< ID >

50、; 123456 </ ID ></ Record ></ Records >报文说明:标签名/说明<XmlData>报文数据主体<Description >报文头部信息<Records>h己录集合|<Record >一行记录<UserInfo >业务认证的用户信息、|<User>业务用户登录名一|<PassWord>业务用户验证口令|<ID>文档的ID,在新增上一个文档的时候,这个ID永远都是空的.外协系统根据这个文件ID是否为空来判断是否是新的文件.<F

51、ILE_PRJ_ID>文档所属的工程ID,对于工程协作系统来说,一个文档永远都是会属于某 个工程的.这个工程ID可以是一级工程,也可以是三级工程.<FILE_TYPE>文件类型.标识文件的归类.比方：D401施工组织设计=401D40碗工工程方案进度 =402D40涮工日报=403<FILE_TYPE>里面的值是代码,文件类型的代码可以从字典接口中获得.<FILE_NAM文档的文件名称,带有扩展名.<FILE_UNIT>文件创立单位,中文名<FILE_MAN>文档创立人上传人<FILE_CREATE_TIME文档创立时间<

52、FILE_AUTHOR文档作者可为空<FILE_TITLE >文档标题可为空<KeepMutiFile >是否允许多个文档同时有效.这个标签的值为1或0.当值为1的时候,那么在同样的工程ID、同样的文件类型中,同时可以存在多个的文档同时有 效存在.这种情况下,多个文档之间是兄弟之间的关系,当前的文档是弟 弟,以前的文档是兄长.当这个值为 0的时候,贝U在同样的工程ID、同样 的文件类型中,只有最后上传的文档有效,后面上传的文档会把前面的文 档“挤到历史中,成为当前文档的“父亲.这种情况下,当前的文档 和以前上传的文档之间是父子的关系.更详细的解释请参见后面的“一条 记录

53、中一个FileID的字段如何上传多个文件主题相关内容.<FileData >文件实体内容.文件实体内容用二进制读取出来之后,然后转换成base64 的格式.<Result >反应报文中的保存成功与否信息.X如果保存成功,那么信息是“成功/如果保存失败,那么信息是“失败：后面是错误的详细信息8.2.6 一条记录中一个文档字段上传多个文件外协系统中,文档是以一种“有关系的方式来存储的.假设有这样一个业务表Tablel ,里面有一个文档的外键字段 File_ID .当我们往Tablel表里面插入一条记录的时候,针对这一条记录, 我们希望在File_ID字段中可以带有多个的文档

54、, 也即会有多个的File_ID .当然,我们可以把这个表字段的数据模型这个定义：File1_ID , File2_ID,File3_ID ,需要多少个文件,我们就 定义几个的File_ID 字段.但是这样就会带来问题了,如果你定义了5个的File_ID 字段,但是,用户如果想在一条记录中上传6个文档,那么,这样的数据模型就会满足不了用户的要求.还有一种 情况,如果用户仅仅上传了 2个文档,那么剩下的3个File_ID字段就会白白空着.甚至用户对这条记录没有上传文件,这样定义的数据模型就白白浪费了数据库的资源.还有一种说法,我可以用记录的形式来表示啊.对的.上传多个文件,是可以在Tablel中

55、新增多条记录方式来表示.但是,我们的前提是,Tablel是一个业务表,里面的一条记录就是一笔业务.如果你产生了多条记录,那么意味这这样的业务进行了屡次.显然违背了业务数据保存的初衷./夕卜协系统弓I入了 “父子,“兄弟的文档保存机制,即在文档信息表Files 表中保存文档的根本信息和他们之间的关系.在同样的工程ID、同样的文件类型中,如果可以存在多个的文档同时有效存在,这种情况下,多个文档之间是兄弟之间的关系.后来者文档是弟弟,先到的文档是兄长.在同样的工程ID、同样的文件类型中,只有最后上传的文档有效,后面上传的文档会把前面的文档“挤到历史中,成为当前文档的“父亲.这种情况下,后来的文档和以

56、前上传的文档之间是父子 的关系.如果文档之间是兄弟关系的话,那么仅仅在业务表Tablel中保存最小兄弟的File_ID ；如果文档 之间是父子关系的话,那么仅仅保存最小辈分的文档File_ID o兄弟和父子的文档保存方式其实都是多个文档串联的一种保存方式,但是,还是会有使用上面的区别的.兄弟关系一般使用在文档之间是平级的情况下.比方施工组织方案,可以有多个文件,但是,这多个文件是互为补充的一局部,互相依赖,又缺一不可.这种情况下,施工系统可以把这类型的文 件上传给外协系统,以兄弟的方式保存,施工系统仅仅在业务表当中保存最后上传反应回来的FileID即可.以后,可以使用这个最小兄弟的File_I

57、D ,向外协系统请求以获得他的所有兄长文档.父子的关系一般使用在下面的情景：当仅允许一个文档是最终有效的时候,或者一个文档修改之后再上传到 外协系统,我们想把最后上传的文档“覆盖前面的文档, 但是,又想保存文档历史修改痕迹的时候, 一般就会用到父子关系.父子关系中,施工系统仅仅需要保存最小辈分的文档信息,以后,可以使用这个最小辈分 的File_ID ,向外协系统请求以获得他的所有历史文档.8.2.7 补充上传文档根据前面的兄弟和父子关系的说明,一条记录中补充上传文档的方式就简单了许多.只要施工系统上传了文档,获得最后的文档 ID,然后,在施工系统中维护最后的文档ID,再用修改记录的报文上报更新

58、后的业务数据即可.流程：上传补充的文档获得最后的文档ID 用最后的文档ID更新业务数据上传修改后的业务数据.8.2.8 在记录中删除一个文档向外协系统请求删除一个文档,只需要向外协系统提交包含有要删除的文档ID即可.如果需要删除的是文档链当中的某一个文档,那么需要向外协请求获得文档链的信息参见后面的“如何获取文档信息,然后,从链中找到要删除的文档ID,向外协系统提交.外协系统在删除文档的问时,会自动把链连接起来成为一个完整的链关系,问时,总是返回链的最末尾的文档ID.施工系统获得链末尾的最后文档ID之后,更新业务表中的相应记录,再用修改的报文上报修改后的业 务数据此步骤不要忘记.请求删除文档的

59、报文：<? xml version="1.0"encoding="utf-8"?>< XmlData >< UserInfo >< User > ZhangSan </ User >< PassWord > 123456 </ PassWord ></ UserInfo >< Description ></ Description >< Records >< ID > 123456 </ ID >&l

60、t;/ Records ></ XmlData >响应报文:报文说明:标签名 说明/<XmlData>报文数据主体|<Description >报文头部信息/|<Records>记录集合/|<Record >_行记录<UserInfo >业务认证的用户信息/<User>业务用户登录名/<PassWord>业务用户验证口令/|<Result >:反应报文中的保存成功与否信息.|如果文档删除成功,那么信息是“成功如果文档删除失败,那么信息是“失败：后面是错误的详细信息请求报文中<

61、ID>文档的ID.要删除的文档ID反应报文中<ID>文档的ID.当删除链中的一个文档之后,外协系统自动维护链之间的关系, 并返回链末尾取后一个文档的ID8.2.9获得文档的根本信息施工系统根据文档的ID向外协系统请求获得文档的根本信息.外协系统返回满足结果的文档基本信息.施工系统可以请求一个文档的根本信息,也可以请求多个最多100文档的信息.这个接口不考虑文档链的情况,仅仅是按指定文档ID返回结果.请求报文：<?xml version="1.0" encoding="utf-8"?><XmlData><UserInfo ><User>ZhangSan</ User><PassWord>123456</ PassWord></ UserInfo ><Description ></ Description ><Records><Record><ID>123456</ID></ Record ><Record><ID>456789</ID&