通过WebApi+FTP为三方提供报告的案例分享

魏小棚

一、需求背景
●在我们构建的系统当中，如果业务的产出包含了结果或者报告，那么难免会涉及到其他系统需要采用其结果或者报告的业务需求。比如我们正在构建检验系统，会涉及到临床要采用检验结果，那么就需要考虑在什么时机，通过怎样的传输方式，以怎样的数据形式进行结果的传输。
●简单的了解整理了下，常用的时机、传输方式及数据形式有以下几种：


●我们此次分享以“中联专业版微生物系统”（后简称为微生物系统）为大蓝本，以“移动临床获取患者微生物报告”为例来聚焦阐述。
详细的需求有：
1、通过具体的报告ID能获取到对应的单份报告
2、通过患者识别信息能获取到患者当此住院的所有报告
3、通过医嘱id来获取医嘱对应的所有报告

二、确定方案
1、时机方面
因为面向的其他系统有需要主动发送报告过去的，也有自己来获取的，所以方案上我们两种时机都支持。
2、数据传输方式
在已知的集中传输方式中，我们最终选择的是通过webapi结合ftp文件服务器的形式来实现。主要的逻辑关键步骤是：

a、报告审核的时候将报告文件通过文件系统上传到ftp文件服务器中。
b、移动临床系统通过一定的条件来调用webapi获取符合条件的报告列表，其中报告每个报告的ftp位置
c、移动临床通过获知的ftp位置到ftp服务器去下载报告。
----------------------------------
3、为什么这么选择呢？主要理由有：
■目前BH提供的对外接口只有webapi；
■webapi可以提供地址给移动临床，也可以将报告文件流信息或者数据给移动临床，但后者推测可能导致性能问题（报告不小，推测待证实）且敏捷不建议这种使用，因此综合选择前者。
■动态库方式不管是初步完成还是后续维护上，对构建人员的要求偏高，而且对别人调用的实现人员要求也高；
■数据库对象的话安全性不好保障，感觉不怎么“专业”；
■文件系统，BH可以通过文件系统上传文件到FTP服务器，不过单文件系统的话对方无法独立获取到具体的路径位置，且实现功能单一不便调试跟踪，因此以此协作；
■其他原因：构建人员本身的知识储备以及构建维护成本

三、实现步骤
1、FTP服务器部署——提供报告文件上传和下载
1.1、添加IIS角色
在应用服务器端，通过服务器管理工具添加【Web服务器(IIS)】的角色

1.2、创建ftp服务器角色服务
1.2.1、在1.1中添加完角色后，添加管理工具控制台和ftp的角色服务

1.2.2、创建ftp读写专用账户（BH报告上传）以及ftp报告读取账户（三方系统使用）
●BH文件系统专用读写用户：

●为三方提供的ftp报告下载读取用户：

1.2.3、创建和配置ftp服务器

1.2.4、测试ftp访问


说明：
●如果外机访问不到，请尝试关闭防火墙或者增加ftp的端口规则
●上面采用的是微软自带的iis服务器创建ftp服务器，除此之外，大家还可以使用类似于ServU等软件来创建
●不管采用什么方式来创建，建议将BH写报告的用户和提供给三方报告的用户分离开来处理读写的权限，安全安全安全

1.3、BH部署文件系统
创建一个文件系统，通过ftp连接的方式连接到之前配置的ftp服务器目录

注意：如果该ip下有多个ftp服务器，需要填上端口用来区分。建议不管有几个都加上端口

1.4、BH处理报告文件上传
1.4.1、上传文件
在业务处理的逻辑中增加一条分支任务，通过“上传文件”操作，将报告的文件流信息上传到部署好的文件系统当中待用。


1.4.2、后期优化想法
●上传文件不能放在实时事务当中
●上传文件不是及时业务，而且容易中断影响业务，因此考虑在审核的时候写一条待上传任务，后面通过job方式单独上传，不影响程序本身执行。当然，如果BH应用服务器本身能支持这种异步上传任务的处理更好了

2、webapi服务部署——提供报告路径查询
环境要求：服务器端有安装.netFramework4.5及以上版本组件
2.1、开启webapi
a、在服务器端运行“服务器配置”程序（…\ApplicationServer\AppServerCfg.exe），找到 【授权&基础】勾选【开启WebAPI】选项，然后对服务参数进行设置。

涉及到的配置参数有：


说明：
●这里有HTTP和HTTPS两种方式，一般对安全性要求不高的环境或者开发、测试环境可以用http方式就可以了，针对院内独立环境使用，前者也够了。
●如果是要使用HTTPS方式，需要独立的证书，以此可以提高访问安全。证书的获取目前知道的有两种：自己网络上购买；敏捷提供“简版”证书。
●环境要求：服务器端有安装.netFramework4.5及以上版本组件

b、设置完成后重新启动BH服务，会显示webapi的信息。

--这里如果是https方式的话，提示有所不同，如果这里遇到问题，BH知识库的webapi部署文档中有常见问题解决方案。

复制其中的地址（我这里是：http://192.168.32.201:8888/help）到浏览器打开，出现以下界面说明设置成功。


2.2、创建接口逻辑块操作
a、创建一个逻辑块操作，用来处理给定查询符合查询条件的所有报告的路径地址并返回。
入参：报告查询条件，与移动临床沟通确认
出参：符合条件报告的路径地址json组，与移动临床沟通确认


b、该逻辑块操作的操作属性中需勾选【支持服务端运行】属性

重要说明：通过与敏捷开发人员确认，【支持服务端运行】属性能否勾选有个前提条件，那就是这个智能操作的内部过程操作必须在下表的范围：

如果超过这个过程操作范围会报错：


2.3、发布webapi服务
a、在领域管理中找到处理报告业务的包，点击工具栏【新增逻辑块操作】按钮，在弹出的“挂接公用逻辑块”二级窗体中定位并勾选2.2中创建的操作，保存退出。


b、通过列选择获取到发布的领域方法的ID，通过以下方式进行webapi的调用
●列选择暴露出ID列，获取ID：

●组织webapi服务调用串：

---------------------------------------------
★至此，webapi的基本配置已经完成，可以进行调用测试。但是要更好更有效利用webapi服务，还需进行以下处理：
---------------------------------------------
2.4、 增加Basic认证名单
目的：实现免密访问。在BH 的WebAPI功能中，提供了支持认证名单，每条规则由用户名和IP组成，符合条件的请求就直接通过认证，无需走密码通道。
部署方式：
a、在服务端增加这个文件（... \ApplicationServer\Config\WebAPI\ authorize.json），文件的内容为：

其中：
●记录1表示用户admin在IP地址192.168.32.71上访问api无需走密码通道；
●记录2表示任何用户在IP地址192.168.32.71上访问api无需走密码通道。
注意：
●BH版本3.6.010及以上版本才支持记录2的形式，之前的版本仅支持记录1的形式
●在编辑的时候注意不要留下多余的空格，会影响到正常解析

2.5、配置领域方法别名
目的（应用场景）：对webapi服务的访问格式为固定前缀加上领域方法的id，一旦领域方法需要修改后重新挂在发布后id发生了改变，此时调用api服务的地址发生改变，影响到了外部系统。使用别名后产生一个别名与领域方法id的对照关系，当webapi服务需要变动时，仅需要更改服务名称与领域方法ID对照即可，对外部系统的访问没有影响。
为了方便理解，画了个简图，见下：


部署方式：在服务端增加这个文件（... \ApplicationServer\Config\WebAPI\bizdomain.json），文件的内容为：

（依然需要注意多余字符，比如空格）

3、调用测试使用webapi测试工具对api服务进行测试

这个测试工具通过下面的地址下载：
\\192.168.0.112\7.zlbh相关\ZLBH版本发布\外围工具\WebAPI测试工具20190114.zip

四、总结
（一）首先对重点过程回顾
1、搭建报告的存储位置和通路（FTP）
（1）搭建FTP服务器，可用微软自带IIS或者三方软件，尽量使用专用账户
（2）配置BH文件系统，有FTP方式和文件共享方式，推荐前者
（3）通过文件系统的“上传文件”完成报告上传逻辑
2、部署提供给三方的webapi服务
（1）服务端开启webapi
（2）处理位置计算逻辑块，并将操作开启服务端运行。需要注意“支持服务端运行”的开启条件
（3）发布webapi服务。挂载位置处理逻辑操作为领域服务，取得webapi服务ID
（4）配置webapi服务的访问basic认证白名单以及别名，提高访问效率和可维护率
        ●增加Basic认证名单能够实现固定ip或者用户的免密访问
        ●增加领域方法的别名能够在发生领域id变动情况下不需要三方作出修改
（5）测试……

（二）针对涉及知识点的思考和补充
1、IIS服务器搭建，web服务器和ftp服务器的区别
在这个案例中，从功能上讲，web服务器也能满足提供可下载文件目录的需求，只需要开启web服务器的目录浏览即可。对于此，相当于web服务器和ftp服务器均能满足这一单一需求。不过在我的认知中，web服务器主要是用来提供网页浏览的，ftp服务器才是用来作为文件传输的，当然，正常情况下两者是合作的，比方说web服务器搭载网络访问，涉及到需要下载的内容就用ftp服务器来完成，这种交替方式形成一个项目的合作。不过针对目前的单一需求，个人选择还是优先ftp服务器吧，web服务器在这种使用场景下总感觉怪怪的。

2、文件系统的配置，ftp与文件共享的区别
我们BH的文件系统目前支持两种方式，一种是ftp，一种是文件共享。针对这两种方式我也简单的了解下，普遍的说法有：
●功能及安全性方面。
ftp可跟踪的内容更多更安全，比如权限管理、日志记录等等；共享是对内网的一个用户间资源的共享，功能很单一，没什么安全在里面
●所用的协议不同。
共享用UNC路径(通用命名协议)访问,而FTP则是用FTP协议,大广域网上更为广泛的使用。
●工作模式不同
FTP支持多用户，断点传送；共享的话，如果不是服务器，则只有10人同时可用，不支持断点传送。
--------------
那么针对此次的案例，可以将ftp服务器对应的文件夹设置为共享后，BH通过共享文件夹的方式来上传报告。但是在提供给三方调用的时候，不建议直接共享目录给对方，还是通过ftp走，理由嘛，安全安全安全，同时方便管理。
如果是完全测试环境，也可以一个共享文件夹走天下，也就是上传报告和提供三方都用共享目录。正式环境不推荐。

3、关于报告上传的时机
报告的上传前面也提到了，首先因为“上传文件”不能放在实时事务当中，因为其极可能导致异常中断，而且整体来看不是即时业务，可以异步上传。所以，后期的改良优化会考虑创建一张任务表，报告审核的时候往表里写一条待处理任务，然后轮循任务进行单独的报告上传工作，避免因为上传文件导致的问题影响到业务执行本身。
另一方面，前期有次审查会也提到了，如果BH应用服务器本身支持这种异步处理的任务能更好支持这个功能。

刘新颜

魏小棚 发表于 2019-5-10 10:26
从“视觉检索”方面来考虑，增加日期的分层存储有一定的必要性——肉眼更好找东西，另外我不是很确定这方 ...

我们这边要简单得多，前面很你的部署一样，FTP，文件系统，BH操作现实上传。文件夹多级不会影像传输的效率，我们的格式是 当前日期/唯一标识号/序列/文件名。我们会将文件路径写到数据库内。
传输的时候我们只会给接口方文件数据路径，这样方法就灵活多样；接口下载我们不关心，只需要对给接口的用户名权限进行设置就能很好的管理

蒙山会

目前我在BH创建WEBAPI,同时提供给第三方地址：http://132.147.166.207:8001/bizd ... 7-b12b-b10db5714f25，但是BH返回提示：“获取领域方法信息失败”，这个问题如何处理？是什么情况呢 ？

陈欣

1、如果是自定义报表生成的PDF文件还有另外一种思路可以考虑，在需要的时候生成pdf文件给对方。（需要更具应用场景具体选择）
2、ftp路径直接固化在表达式里面不利于地址变更。

贺伟

魏小棚 发表于 2019-5-10 10:26
从“视觉检索”方面来考虑，增加日期的分层存储有一定的必要性——肉眼更好找东西，另外我不是很确定这方 ...

       ftp一般是做文件上传处理，建立文件信息表（记录文件id，文件MD5及文件路径），然后web服务通过文件id来提供文件流的输出，这样业务系统记录的文件信息和实际的文件路径没有任何关系，存储的文件信息也更加友好，文件目录结构就可以做更精细化的分类。
       第二点就是ftp上传还需要考虑重复资源存储的问题，相同文件不应该多次进行存储，浪费了存储资源

魏小棚

补充：
●以上是对整个方面能想到内容的描述，如果有什么问题或者错误麻烦提出来我修改。这一楼就开着用于后面的补充
●针对报告的异步上传不知道大家有没有比较好的方案，欢迎提出来沟通

范俊

魏小棚 发表于 2019-5-5 03:10
补充：
这个方案算是我在完成这个需求的摸索过程，中间方案选择上考虑的是实现优先，对于安全性方面的考虑 ...

一个思路：报告文件生成到本地指定目录，利用客户端的“本机定时器”处理上传逻辑。

魏小棚

范俊 发表于 2019-5-6 11:21
一个思路：报告文件生成到本地指定目录，利用客户端的“本机定时器”处理上传逻辑。

范兄这是一种方案，确认下呢，这个方案是不是要客户端一直挂起？
可否有能让服务端执行的方案，或者服务端安装一个客户端挂着，然后来处理任务？

范俊

魏小棚 发表于 2019-5-7 23:03
范兄这是一种方案，确认下呢，这个方案是不是要客户端一直挂起？
可否有能让服务端执行的方案，或者服 ...

1、我的理解，文件生成应该是在客户端。（如果已经都上传到某个服务器了，这个问题都没了）
2、其实吧，这类需求不应该是BH客户端来做的。我的建议方案（可行性再谈）：
  a)如果是基于很多台客户端的文件收集。在客户端安装一个后台程序，用于处理文件上传等后台长期运行的动作。
  b)如果是某个特定机器上的文件处理。可以直接写个独立的插件程序，或者直接用陈亮白天他们做的“上传工具”来实现。

卢彦伯

不知道微生物系统是否有考虑，所有报告全部放在FTP的一个文件夹下，还是有按年或者按月分文件夹来存储？

魏小棚

陈欣 发表于 2019-5-9 16:48
1、如果是自定义报表生成的PDF文件还有另外一种思路可以考虑，在需要的时候生成pdf文件给对方。（需要更具 ...

欣爷讲的之前也有过一定的考虑：
1、我们使用的自定义报表导出pdf或者xps，使用的动态库功能，也沟通过直接传输报告文件流的方式。不过这个案例的三方他们需要pdf文件，于是就通过文件系统方式走了。
2、地址那个之前考虑过使用规则的，不过因为文件系统配置那里用不了规则，实际使用只有这一处，加上每次改动都需要确认调整，所以暂时没有使用。如果规范点应该是欣爷说的这种使用规则。

魏小棚

卢彦伯 发表于 2019-5-10 08:58
不知道微生物系统是否有考虑，所有报告全部放在FTP的一个文件夹下，还是有按年或者按月分文件夹来存储？

从“视觉检索”方面来考虑，增加日期的分层存储有一定的必要性——肉眼更好找东西，另外我不是很确定这方面在构建规范上是否有规定，加上我们目前的文件命名方式是【ZLHIS的报告ID】+【格式后缀】来的，以患者角度拉报告清单目录是一致的。不过关键一点，系统或者三方系统通过ftp来访问和下载报告文件，是否会受到路径层级影响，或者上传是否时间会不一致需要后续验证做个确认，不过个人判断影响应该不大。
综上，肉眼检索方面考虑可以增加层级，同时需要验证性能上面是否有明确区别，如果有验证过这个大大分享下经验更好了  哈哈

冉俊明

都是大牛啊，不错，多多分享！