中山大学数据共享交换平台接入规范Word格式文档下载.docx

中山大学数据共享交换平台接入规范Word格式文档下载.docx

《中山大学数据共享交换平台接入规范Word格式文档下载.docx》由会员分享，可在线阅读，更多相关《中山大学数据共享交换平台接入规范Word格式文档下载.docx（89页珍藏版）》请在冰豆网上搜索。

4.2.消息定义30

4.2.1.消息体30

4.2.2.系统ID（系统编码）31

4.2.3.接口编码31

4.3.接口详细设计33

4.3.1.资源目录管理33

4.3.2.数据文件请求模式接口37

4.3.3.数据报文请求模式接口41

4.3.4.数据采集服务接口43

4.3.5.供数服务44

4.3.6.点对点供数45

4.3.7.数据文件推送46

4.3.8.数据报文推送48

4.3.9.消息通知模式49

4.3.10.通报交换（不固定周期）50

5.数据权限51

5.1.资源权限51

5.2.字段级权限51

6.附录1—错误码52

7.附录2—web服务使用说明53

7.1.使用交换平台的接口53

7.2.接入方实现的服务55

7.3.报文样例57

1.概述

中山大学数据共享交换平台（下称“交换平台”）是负责传输校内不同信息系统间数据的平台，各业务系统通过与数据交换平台对接，实现业务数据在不同业务系统之间顺畅、实时、批量传输。

1.1.读者

Ø

与交换平台对接的信息系统建设方

与交换平台对接的信息系统开发方

交换平台开发方

交换平台运维管理方

1.2.目的

本文档是中山大学数据共享交换平台接口需求及设计方案相关文档，可用于指导对接接口开发、联调、测试工作。

1.3.相关术语

术语

说明

数据共享交换平台

下文如无特殊说明，简称交换平台。

业务系统

需要实施数据共享交换的业务信息系统，如人事信息管理系统、教务信息管理系统等。

ok文件

标志文件，在数据文件生成完成后产生的空文件，供数据需求方判断文件是否可读取

资源代码

资源如果是数据库表，则资源代码为：

数据提供方表名。

资源如果是文件,则资源代码为：

文件名去掉系统ID和后缀。

资源如果是报文，则资源代码为：

返回报文中result中的tablename。

dcroot

交换平台sftp根目，实际为登录后的files目录

syroot

交换平台为每个业务系统配置的专属sftp根目录。

不同的业务系统的根目录不同，实际为登录后的files目录

单一资源

资源目录中一个资源ID定义为一个资源，当资源为一个文件或一个表时，为单一资源

复合资源

资源目录中一个资源ID定义为一个资源，当资源为一类资源，即对应多个文件或多个消息时，为复合资源。

例如一份完整档案，包含多个不同类型文件集合，此集合属于一个复合资源。

1.4.信息资源目录

信息资源目录为数据共享交换的依据，目录所含内容既是对共享信息资源的描述，也是数据交换关系的描述。

在数据共享交换中的一张数据库表、一个文件或一类文件都是属于信息资源，注册于信息资源目录中。

中山大学信息资源目录由数据模型管理平台管理，数据共享交换实施前需要数据提供方注册，并由数据管理员审核通过后对全校发布。

下表详细介绍资源的属性

字段名称

字段类型

是否必填

resourceID

String

是

资源ID，一个资源的唯一ID

multiFlag

char

是否包含多个文件标识：

S：

单一资源（对应一个文件，一个表）；

M：

复合资源（可多个文件，多个消息定义为一个资源ID，对应一类资源，一类消息）。

resourceAlias

资源代码：

（1）当multiFlag=S时：

数据库表为：

数据提供方表名,

文件类型为：

文件名去掉系统ID和后缀,

报文类型为：

返回报文中result中的tablename；

（2）当multiFlag=M时：

自定义的这一类资源的类别名称，如果是文件类型，建议使用这一类文件的名称统一前缀。

提交资源是确保本系统唯一。

注：

受限于oracle对表名的限制，时分频率供数时表名为{providerSysID}_{resourceAlias}_{reqSysID}，资源代码最长只能为22位；

remark

资源描述

resourceType

Char

是否结构化数据：

（1）结构化数据：

S。

类似数据库格式化的数据，有字段说明的数据；

（2）非结构化数据：

N。

非结构化数据，如图片文件。

providerSysID

数据提供方ID。

见3.2.2系统ID章节

isStore

数据是否在中心交换节点留存：

Y-代表数据在交换过程中会在中心节点留存，即数据交换过程中数据会在交换平台“落地”；

N-代表数据在交换过程中不在中心节点留存，即数据交换过程中数据只交换，但不会在交换平台“落地”。

frequency

否：

非定时数据交换方式可为空

数据交换任务定时启动的频率定义：

minute:

30含义是交换任务从每日0点起每30分钟运行一次；

60含义是交换任务从每日0点起每60分钟运行一次；

day含义每日运行一次；

week:

n含义周几运行，如周一，则n=1；

month:

两位日期含义每月运行一次，如month:

02为每月2日运行；

year:

四位日期含义一年运行一次，如year:

0321为每年3月21日运行；

putTime

数据提供方完成供数的时间点，格式为HH:

mm，此字段与frequency结合使用，用于表述某天某日定时数据交换的时间。

例如：

……

getMode

数据提供方资源承载方式：

F：

文件方式

D：

数据库方式

I：

报文方式

普通通知类消息（双方直接通讯方式的资源定义）

isIncrease

否

是否增量：

Y-增量、N-全量。

如是增量，中心库需追加；

如是全量，中心库需覆盖。

如数据提供方有物理删除数据，需要写入交换节点机并打D标识。

增量的数据必须包括当期新增、修改、删除的数据（业务上逻辑删除的数据为修改）。

新建业务系统必须提供增量供数模式，不再接受全量供数模式

increaseParam

数据库增量抽取的时候必填

增量抽取sql中where条件后面的内容。

如条件中有数据日期，请使用格式化参数代替，前后加上‘#’

1、日期使用#yyyyMMdd#或#yyyy-MM-dd#

2、日期时间使用#yyyyMMddHHmmss#或#yyyy-MM-ddHH:

mm:

ss#

实际执行时日期参数使用具体日期替代，需能够抽取到当期新增和修改的数据（业务上逻辑删除的数据为修改）

比如资源定义：

lastTime>

=to_date（'

#yyyy-MM-dd#'

'

yyyy-mm-dd'

）

实际使用时：

C001需传入:

2017-10-31'

平台采集时：

数据日期说明见1.7，与实际运行日期不同

isLogTable

是否流水表，流水表只能为增量抽取。

Y-是；

N-否

流水表不处理增改删标志，默认只有新增。

catalog

资源类别：

B-基础数据

S-业务数据

C-决策数据

具体定义见附录:

资源类别定义

theme

string

所属主题

教职工域

教学域

财务域

学生业务域

科研域

1.5.数据交换方式

1.数据库方式：

数据供需双方可通过读写交换节点上数据库的表或视图实现数据交换。

2.文件方式：

数据供需双方可通过读写交换节点上的文件实现数据交换，如是结构化数据，需要按照接口文档中描述的文件格式提供文件，以便于交换平台对文件解析。

3.web服务方式：

数据供需双方可通过提供webservice对提供和获取数据，webservice需按照接口文档中的描述方式实现，为httppost方式的RESTful方式，参数为Json格式，即需按C001接口实现。

详见4.3.3章节。

1.6.数据交换模式

1.实时交换：

通过B001，C001，H001，I001等接口请求的数据，会实时返回或生成数据。

2.轮询交换（固定周期）：

此方式下，数据提供方或者数据需求方在资源目录中约定数据交换频率（如30分钟一次、1日一次等），并按照该频率，数据提供方提供数据到交换平台，数据需求方定期从交换平台轮询获取数据。

此方式下，交换平台不会主动告知各方是否有更新数据，需要数据需求方定期轮询。

3.通报交换（不定周期）：

此方式下，业务数据数据发生变更后，数据提供方即时主动通报数据交换平台，由数据交换平台把数据推送给数据需求方，同时通报数据需求方从交换平台获取数据。

此种交换方式频率不固定。

1.7.数据日期概念

，提供方生成文件需要加上数据日期，文件命名和要加上数据日期，即下文中yyyyMMdd和yyyyMMddHHmm，数据日期与实际运行日期是有区别的，实际处理数据是上一期（配合增量条件）的数据，所以数据日期=实际日期-周期。

采用数据库交换方式时，交换平台会在交换表中建时间戳内建字段。

下面给出具体的例子

周期

运行日期/时间

数据日期/时间

30

201803291130

201803291100

半点和整点运行

60

201803291000

整点运行

day

20180329

20180328

每天运行

5

20180406

20180326

（上周周一）

每周五运行

01

20180402

20140301

（上月1日）

每月1日运行

0301

20180301

20170101

（上年元旦）

每年3月1日运行

1.8.增量条件

数据提供方提供数据可以是增量也可以是全量，原则要求初次提供全量数据，日常提供提供增量数据。

为了保证交换平台的数据与源系统数据语义一致，业务系统发生数据新增、修改、删除数据的操作，都应按照增量方式把数据提交给交换平台。

数据增加标识字段为A，数据修改的标志位为U，数据删除标识位为D，后续章节将具体介绍。

增量条件中日期部分，请使用格式化参数代替，前后加上‘#’字符

实际执行时日期参数使用具体数据日期替代，需能够抽取到当期新增和修改的数据（业务上逻辑删除的数据为修改）。

例如资源定义：

='

2.交换体系设计

2.1.总体设计

数据交换平台提供各业务系统数据接入的接口，实现数据交换平台和各业务系统的有机结合，以统一的数据模型、数据质量标准和接口规范实现数据自动提取、转换、发送、校验与审核，同时支持数据同步、历史数据迁移等。

数据交换平台以“统一标准”、“统一处理”、“统一交换”、“保证质量”、“透明开发”的方式，为不同业务系统、数据库和数据格式之间进行数据的交换提供服务。

数据交换平台通过平台提供的接口规范与接入系统进行通信，以完成数据交换和消息传递的功能。

其业务流程具有以下特点：

1.实时、准实时数据交互：

如果交互的数据量较小，实时性要求高，可采取数据报文模式，可以实现数据的实时交互；

如果数据量较大，则可以采取数据库或文件的方式。

2.主动被动模式：

数据可以由数据需求方主动请求，也可由数据提供方主动推送。

2.2.架构设计

2.2.1.SFTP服务架构

数据交换平台中心节点架设sftp服务器，实现文件的上传和下载；

为每个接入的系统建立一个sftp用户，并设置专属sftp目录。

为保证文件的安全性，sftp用户只能访问向其开放的专属sftp目录，不能访问其他用户目录的数据文件。

接入系统上传和下载文件也只能通过其专属的sftp目录实现。

上传和下载的文件目录为sftp登录后的/files/目录。

2.2.2.数据库物理架构

交换平台提供数据库交换节点供业务写入数据和读取数据，交换节点为每个业务系统分配一个账号。

管理员或提供方建立资源后，交换平台会在交换节点机建立供业务系统写入的表，表名定义为源系统ID_资源代码。

供数给业务系统时，交换平台会把数据写入交换节点机，表名定义为源系统ID_资源代码_需求方系统ID。

2.3.数据交换方式

数据交换方式分为三种：

文件，数据库，web服务。

他们是资源的承载方式，在资源管理系统上注册资源的时候，可以指定其中一种方式。

2.3.1.文件方式交换

2.3.1.1.轮询交换（固定周期）、通报交换（不固定周期）提供的文件

数据文件每一行的数据表示数据库中一行数据，使用unix换行符换行；

文件不包含表头的字段名；

字段之间使用16进制0X1B间隔；

blob二进制字段有可能包含字段分隔符0X1B，文件提供方需进行base64编码；

数据库字段值为null的，写入文件为空值

不需要文本限定符，即字段不需要使用引号包含起来；

日期字段格式需格式化为yyyy-MM-dd；

时间字段格式需格式化为yyyy-MM-ddHH:

ss；

文件数据编码为UTF-8

在数据原有的字段后面新增三个字段：

（1）数据新增、删除、修改标识：

A：

新增；

删除；

U：

修改.

（2）数据日期标识：

标识数据日期yyyyMMdd或yyyyMMddHHmm.（3）时间戳

1、资源目录中标识为流水表的，增改删标识设置为A-新增；

2、数据标识只针对数据本身，无业务含义，业务系统当前批次逻辑删除的数据，记为U-修改。

3、文件中数据不能含有换行符，如有换行符和制表符，需要直接删除，或替换为<

BR>

换行符ASCII码为char（10）,char（13）,char（27）

4、如果提供轮询交换模式的文件资源，提供方在每个周期都需上传文件，如增量方式提供且当期没有数据，也需提供空dat文件和ok文件。

5、需求方获取数据文件（dat文件）前，需要判断是否存在ok文件，以确保文件完整性。

2.3.1.2.实时交换方式提供的文件

实时交换提供的文件，即一次性请求的文件（如B001接口），文件格式参考上节所述提供的文件格式，只是不需要新增三个标识字段。

2.3.1.3.文件路径说明

文件路径和文件名设置，预定义dcroot为交换中心sftp登录后/files目录，syroot为业务系统sftp登录后/files目录。

下文“xxx”，在单一资源时为资源代码，在复合资源时为报文中定义的文件名。

（1）实时/通报模式文件（B001接口，H001接口）：

1.数据提供方上传文件路径为：

syroot/数据提供方id_xxx.dat，syroot/数据提供方id_xxx.ok；

2.数据需求方文件路径为：

syroot/数据提供方id_xxx.dat,syroot/数据提供方id_xxx.ok。

（2）轮询模式文件采集：

1.年、月、日频率文件命名：

a.数据提供方上传文件路径为：

syroot/yyyyMMdd/数据提供方id_xxx.dat,syroot/yyyyMMdd/数据提供方id_xxx.ok；

yyyyMMdd为数据日期，一般偏移量前一周期（参见数据日期概念），如20180315日处理20180314的数据，那么数据日期为20180314。

b.数据需求方文件路径为：

syroot/yyyyMMdd/数据提供方id_xxx.dat和syroot/yyyyMMdd/数据提供方id_xxx.ok。

2.时、分频率文件命名：

syroot/yyyyMMdd/数据提供方id_xxx_HHMM.dat,syroot/yyyyMMdd/数据提供方id_xxx_HHMM.ok；

syroot/yyyyMMdd/数据提供方id_xxx_HHMM.dat和syroot/yyyyMMdd/数据提供方id_xxx_HHMM.ok。

2.3.2.数据库方式交换

数据库供数到数据库交换节点已建立好的数据表（源系统ID_资源代码）中，表结构中业务字段定义严格按照信息办发布的《中山大学数据资源目录》中的表结构，另外，如增量方式提供数据时，交换平台在交换节点机建表时会添加三个控制字段,适用于轮询交换（固定周期）、通报交换（不固定周期）。

●dc_dcFieldAUDchar

（1）AUD标识：

枚举值：

A，U，D三个值，分别为A-新增，U-修改，D-删除

●dc_dcDataDatevarchar（12）数据日期，更新数据频率大于等于1天时，格式为YYYYMMDD，更新频率小于1天时，格式为YYYYMMDDHHMM，详解1.7

●dc_dcTimeStamptimestamp时间戳

注：

①提供方全量供数则无此三个控制字段

②交换节点机的表由交换平台建立

全量提供数据时，提供方先删除数据表中的数据，然后写入新一个批次的数据。

增量供数时，第一个批次写入全量数据，三个控制字段必须写入数据

•dc_dcFieldAUD=A

•dc_dcDataDate=批次日期

•dc_dcTimeStamp=写入时间

后续批次只需写入增量数据，三个控制字段必须写入数据。

1、需求方获取数据表数据前，需要发送E001确定平台数据是否供数完成。

2.3.3.WEB服务方式交换

数据提供方实现了C001接口服务（参见接口编码），可以通过此服务对外提供数据服务功能。

此中方式较为灵活，数据需求方可在请求中指定条件，能够获取到更为准确的数据。

适合数据量较少，实时性较高的场景。

2.4.系统接入方式

在系统建设期间，由信息办统一规划，批量确定接入数据交换平台的系统。

系统运行期间，接入数据交换平台的业务系统，需要填写数据接入申请单，根据相关规定进行审批，审批完成后，由数据管理员在管理系统上配置系统环境信息并分配操作用户给系统接入方。

系统接入流程

1、业务系统向数据管理员申请接入平台

2、数据管理员审批通过后，分配系统ID（系统ID需统一规划）

3、业务系统提交系统公钥（使用平台秘钥工具产生），数据管理员

4、数据管理员录入提交的公钥和环境信息

通过以上步骤即完成系统接入工作，接入系统可以是如下两种角色，可以在资源管理平台上对资源进行管理和操作

1、数据提供方：

可在提供的管理系统上新建资源，条件共享并审核需求方的权限申请。

2、数据需求方：

可在提供的管理系统上查询资源，并对需要的资源申请权限，权限审批通过后，才可进行数据交换。

3.数据交换模式

完成一次数据交换，需线上和线下共同配合，具体步骤如下

1、管理员在资源管理WEB平台新建接入系统的用户

2、管理员维护提供方或需求方公钥和实时接口的访问地址

3、数据提供方在WEB网站提交新建的资源目录，包括资源的英文名称，数据结构，更新频率等

4、管理员审核数据提供方新建的资源，如数据库资源，平台会在交换节点新建数据库表，供提供方写入数据

5、审核通过的资源即为有效资源，需提供方按照新建资源时设定的频率写入数据（数据库表或文件）

6、管理员对全校发布资源

7、数据需求方线上提交资源需求申请（三种模式：

实时，轮询，通报）

8、数据提供方完成资源授权，完成审批流程

9、数据提供方审批完成后，可进行数据交换

a）实时模式：

接收需求方或提供方的消息报文请求，根据不同消息报文处理实时数据交换

b）轮询模式：

交换平台按照设定的频率读取数据提供方的数据（文件或数据库表），并把数据供给数据需求方（文件或数据库），如需求方提供的数据库环境，则平台在供数前会建立数据库表，表名请参见2.2.2

c）通报模式：

平台接收到数据提供方的K001（参见4.3.10）通知后，会读取更新的数据，推送给有需求的数据需求方

3.1.实时交换

2.

2.1.

2.1.1.数据报文请求

数据报文请求流程图

数据报文请求采用同步方式，数据可由数据提供方提供，也可以由数据库交换节点提供。

具体情况如下：

1.当数据未入中心交换节点数据库，或数据已入中心交换节点数据库，但请求报文时要求数据提供方提供数据，由数据提供方提供C001服务或平台查询交换节点提供方数据库表。

数据交换平台获取数据提供方数据的方式以资源目录定义为准，数据提供方需实现C001数据报文请求服务，提供服务的方式请参见附录2。

数据报文请求——数据提供方提供数据

2.数据已入中心库的，由平台交换节点数据库提供数据。

数据报文请求——平台提供数据

2.1.2.数据文件请求

数据文件请求流程图

1.数据未入中心交换节点数据库：

数据文件请求采用异步方式，B001响应报文成功并不表示文件已生成。

对于未采集到中心库的数据，由数据提供方提供文件或平台查询交换节点提供方数据库表。

数据交换平台获取数据提供方数据的方式以资源目录定义为准，数据提供方需要提供B001和B002服务，提供服务的方式请参见附录2。

数据文件请求——数据提供方提供数据

2.数据已入中心库：

数据文件请求采用异步方式，对于已采集到中心交换节点数据库库的数据，平台生成文件。

数据需求方获取文件可以有以下两种情况，根据B001报文中needNotice字段确定。

（1）为保证让数据请求方及