中山大学数据共享交换平台接入规范

中山大学数据共享交换平台接入规范

(试行)

中山大学信息化管理办公室

2018年5月

目 录

1.

1.1. 1.2. 1.3. 1.4. 1.5. 1.6. 1.7. 1.8. 2.

2.1. 2.2.

概述 ................................................................................................................................... 1

读者 ........................................................................................................................... 1 目的 ........................................................................................................................... 1 相关术语 ................................................................................................................... 1 信息资源目录 ........................................................................................................... 2 数据交换方式 ........................................................................................................... 5 数据交换模式 ........................................................................................................... 5 数据日期概念 ........................................................................................................... 6 增量条件 ................................................................................................................... 6 交换体系设计 ................................................................................................................... 7

总体设计 ................................................................................................................... 7 架构设计 ................................................................................................................... 8 2.2.1. 2.2.2. 2.3.

SFTP服务架构 .................................................................................................. 8 数据库物理架构 ............................................................................................... 9

数据交换方式 ......................................................................................................... 10 2.3.1.

文件方式交换 ................................................................................................. 10

2.3.1.1. 轮询交换（固定周期）、通报交换（不固定周期）提供的文件 ....... 10 2.3.1.2. 实时交换方式提供的文件 ..................................................................... 11 2.3.1.3. 文件路径说明 ......................................................................................... 11 2.3.2. 2.3.3.

数据库方式交换 ............................................................................................. 12 WEB服务方式交换 ........................................................................................ 13

2.4. 3.

3.1.

系统接入方式 ......................................................................................................... 13 数据交换模式 ................................................................................................................. 14

实时交换 ................................................................................................................. 15 2.1.1. 2.1.2. 2.1.3. 2.1.4.

数据报文请求 ................................................................................................. 15 数据文件请求 ................................................................................................. 18 数据报文推送 ................................................................................................. 22 数据文件推送 ................................................................................................. 23

3.2. 轮询交换（固定周期） ......................................................................................... 24 3.2.1. 3.2.2.

采集过程 ......................................................................................................... 25 供数过程 ......................................................................................................... 27

3.3. 4.

4.1.

通报交换（不定周期） ......................................................................................... 28 接口设计 ......................................................................................................................... 30

接口总体说明 ......................................................................................................... 30 4.1.1. 通信模式 ......................................................................................................... 30 4.1.2. 安全控制 ......................................................................................................... 30 4.1.3. 错误处理 ......................................................................................................... 30

4.2. 消息定义 ................................................................................................................. 31 4.2.1. 消息体 ............................................................................................................. 31 4.2.2. 系统ID（系统编码） .................................................................................... 32 4.2.3. 接口编码 ......................................................................................................... 32

4.3. 接口详细设计 ......................................................................................................... 34 4.3.1. 资源目录管理 ......................................................................................... 34 4.3.2. 数据文件请求模式接口 ......................................................................... 38 4.3.3. 数据报文请求模式接口 ......................................................................... 42 4.3.4. 数据采集服务接口 ................................................................................. 44 4.3.5. 供数服务 ................................................................................................. 45 4.3.6. 点对点供数 ............................................................................................. 46 4.3.7. 数据文件推送 ......................................................................................... 47 4.3.8. 数据报文推送 ......................................................................................... 49 4.3.9. 消息通知模式 ......................................................................................... 50 4.3.10. 通报交换（不固定周期） ................................................................... 51 数据权限 ......................................................................................................................... 52

5.

5.1. 5.2.

资源权限 ................................................................................................................. 52 字段级权限 ............................................................................................................. 52

6. 7.

7.1. 7.2. 7.3.

附录1—错误码 .............................................................................................................. 53 附录2—web服务使用说明 ........................................................................................... 54

使用交换平台的接口 ............................................................................................. 54 接入方实现的服务 ................................................................................................. 56 报文样例 ................................................................................................................. 58

1. 概述

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

1.1. 读者

? 与交换平台对接的信息系统建设方 ? 与交换平台对接的信息系统开发方 ? 交换平台开发方 ? 交换平台运维管理方

1.2. 目的

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

1.3. 相关术语

术语 数据共享交换平台 业务系统 说明 下文如无特殊说明，简称交换平台。 需要实施数据共享交换的业务信息系统，如人事信息管理系统、教务信息管理系统等。 ok文件 标志文件，在数据文件生成完成后产生的空文件，供数据需求方判断文件是否可读取 资源如果是数据库表，则资源代码为：数据提供方表名。 资源如果是文件,则资源代码为：文件名去掉系统ID和后缀。 资源如果是报文，则资源代码为：返回报文中result中的tablename。 交换平台sftp根目，实际为登录后的files目录 第 1 页

资源代码 dcroot

syroot 交换平台为每个业务系统配置的专属sftp根目录。不同的业务系统的根目录不同，实际为登录后的files目录 单一资源 资源目录中一个资源ID定义为一个资源，当资源为一个文件或一个表时，为单一资源 资源目录中一个资源ID定义为一个资源，当资源为一类资源，即对应多个文件或多个消息时，为复合资源。例如一份完整档案，包含多个不同类型文件集合，此集合属于一个复合资源。 复合资源 1.4. 信息资源目录

信息资源目录为数据共享交换的依据，目录所含内容既是对共享信息资源的描述，也是数据交换关系的描述。在数据共享交换中的一张数据库表、一个文件或一类文件都是属于信息资源，注册于信息资源目录中。

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

下表详细介绍资源的属性 字段名称 resourceID 字段类型 String 是否必填 是 说明 资源ID，一个资源的唯一ID 是否包含多个文件标识： S：单一资源（对应一个文件，一个表）； M：复合资源（可多个文件，多个消息定义为一个资源ID，对应一类资源，一类消息）。 multiFlag char 是

第 2 页

resourceAlias String 是 资源代码： （1）当multiFlag=S时： 数据库表为：数据提供方表名, 文件类型为：文件名去掉系统ID和后缀, 报文类型为：返回报文中result中的tablename； （2）当multiFlag=M时： 自定义的这一类资源的类别名称，如果是文件类型，建议使用这一类文件的名称统一前缀。 提交资源是确保本系统唯一。 注：受限于oracle对表名的限制，时分频率供数时表名为 {providerSysID}_{ resourceAlias}_{ reqSysID}，资源代码最长只能为22位； 资源描述 是否结构化数据： （1）结构化数据：S。类似数据库格式化的数据，有字段说明的数据； （2）非结构化数据：N。非结构化数据，如图片文件。 数据提供方ID。见3.2.2系统ID章节 remark String 是 resourceType Char 是 providerSysID String 是 isStore char frequency String 数据是否在中心交换节点留存： Y-代表数据在交换过程中会在中心节点留存，即数据交换过程中数据会在交换平台“落地”； 是 N-代表数据在交换过程中不在中心节点留存，即数据交换过程中数据只交换，但不会在交换平台“落地”。 数据交换任务定时启动的频率定义： minute:30 含义是交换任务从每日0点起每30分钟运行一次； minute:60 含义是交换任务从每日0点否：非定时起每60分钟运行一次； 数据交换方day 含义每日运行一次； 式可为空 week:n 含义周几运行，如周一，则n=1； month:两位日期 含义每月运行一次，如month:02为每月2日运行； year:四位日期 含义一年运行一次，如year:0321为每年3月21日运行；

第 3 页

putTime String 否： 数据提供方完成供数的时间点，格式为HH:mm，此字段与frequency结合使用，用于表述某天某日定时数据交换的时间。例如：…… 数据提供方资源承载方式： F：文件方式 D：数据库方式 I：报文方式 M：普通通知类消息（双方直接通讯方式的资源定义） getMode char 是 isIncrease char increaseParam String 是否增量：Y-增量、N-全量。 如是增量，中心库需追加；如是全量，中心库需覆盖。 注：如数据提供方有物理删除数据，需否 要写入交换节点机并打D标识。增量的数据必须包括当期新增、修改、删除的数据（业务上逻辑删除的数据为修改）。新建业务系统必须提供增量供数模式，不再接受全量供数模式 增量抽取sql中where条件后面的内容。如条件中有数据日期，请使用格式化参数代替，前后加上‘#’ 1、日期使用#yyyyMMdd#或#yyyy-MM-dd# 2、日期时间使用#yyyyMMddHHmmss# 或 #yyyy-MM-dd HH:mm:ss# 注：实际执行时日期参数使用具体日期替代，需能够抽取到当期新增和修改的数据（业务上逻辑删除的数据为修改） 否：数据库比如资源定义：增量抽取的lastTime>=to_date('#yyyy-MM-dd#','yyyy-mm-时候必填 dd') 实际使用时： C001需传入:lastTime>=to_date('2017-10-31','yyyy-mm-dd') 平台采集时：lastTime>=to_date('2017-10-31','yyyy-mm-dd') 注：数据日期说明见1.7，与实际运行日期不同 isLogTable char 是 是否流水表，流水表只能为增量抽取。 Y-是；N-否 注：流水表不处理增改删标志，默认只有新增。 第 4 页

catalog char 是 theme string 是 资源类别： B-基础数据 S-业务数据 C-决策数据 具体定义见附录:资源类别定义 所属主题 教职工域 教学域 财务域 学生业务域 科研域 1.5. 数据交换方式

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

据交换。

2. 文件方式：数据供需双方可通过读写交换节点上的文件实现数据交换，如是

结构化数据，需要按照接口文档中描述的文件格式提供文件，以便于交换平台对文件解析。

3. web服务方式：数据供需双方可通过提供webservice对提供和获取数据，

webservice需按照接口文档中的描述方式实现，为http post方式的RESTful方式，参数为Json格式，即需按C001接口实现。详见4.3.3章节。

1.6. 数据交换模式

1. 实时交换： 通过B001 ，C001，H001，I001等接口请求的数据，会实时返

回或生成数据。

2. 轮询交换（固定周期）：此方式下，数据提供方或者数据需求方在资源目录

中约定数据交换频率（如30分钟一次、1日一次等），并按照该频率，数据提供方提供数据到交换平台，数据需求方定期从交换平台轮询获取数据。此方式下，交换平台不会主动告知各方是否有更新数据，需要数据需求方定期轮询。

3. 通报交换（不定周期）：此方式下，业务数据数据发生变更后，数据提供方

即时主动通报数据交换平台，由数据交换平台把数据推送给数据需求方，同

第 5 页

时通报数据需求方从交换平台获取数据。此种交换方式频率不固定。

1.7. 数据日期概念

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

采用数据库交换方式时，交换平台会在交换表中建时间戳内建字段。 下面给出具体的例子 周期 minute:30 minute:60 day week:5 运行日期/时间 201803291130 201803291100 20180329 20180406 数据日期/时间 201803291100 201803291000 20180328 20180326 （上周周一） month:01 20180402 20140301 （上月1日） year:0301 20180301 20170101 （上年元旦） 每年3月1日运行 每月1日运行 说明 半点和整点运行 整点运行 每天运行 每周五运行 1.8. 增量条件

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

为了保证交换平台的数据与源系统数据语义一致，业务系统发生数据新增、修改、删除数据的操作，都应按照增量方式把数据提交给交换平台。数据增加标识字段为A，数据修改的标志位为U，数据删除标识位为D，后续章节将具体介绍。

增量条件中日期部分，请使用格式化参数代替，前后加上‘#’字符 1、日期使用#yyyyMMdd#或#yyyy-MM-dd#

第 6 页

2、日期时间使用#yyyyMMddHHmmss# 或 #yyyy-MM-dd HH:mm:ss#

注：实际执行时日期参数使用具体数据日期替代，需能够抽取到当期新增和修改的数据（业务上逻辑删除的数据为修改）。 例如资源定义：lastTime>='#yyyy-MM-dd#' 实际使用时：

C001需传入:lastTime>='2017-10-31' 平台采集时：lastTime>='2017-10-31'

2. 交换体系设计 2.1. 总体设计

数据交换平台提供各业务系统数据接入的接口，实现数据交换平台和各业务系统的有机结合，以统一的数据模型、数据质量标准和接口规范实现数据自动提取、转换、发送、校验与审核，同时支持数据同步、历史数据迁移等。数据交换平台以“统一标准”、“统一处理”、“统一交换”、“保证质量”、“透明开发”的方式，为不同业务系统、数据库和数据格式之间进行数据的交换提供服务。

第 7 页

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

交换节点数据库SFTP交换节点采集交换引擎交换引擎供数数据库SFTP写入数据数据提供方业务系统业务系统数据交换共享平台消息接口消息接口读取数据数据需求方消息通信业务系统业务系统消息通信 其业务流程具有以下特点：

1. 实时、准实时数据交互：如果交互的数据量较小，实时性要求高，可采取数

据报文模式，可以实现数据的实时交互；如果数据量较大，则可以采取数据库或文件的方式。

2. 主动被动模式：数据可以由数据需求方主动请求，也可由数据提供方主动推

送。

2.2. 架构设计 2.2.1. SFTP服务架构

数据交换平台中心节点架设sftp服务器，实现文件的上传和下载；为每个接入的系统建立一个sftp用户，并设置专属sftp目录。为保证文件的安全性，sftp用户只能访问向其开放的专属sftp目录，不能访问其他用户目录的数据文件。接入系统上传和下载文件也只能通过其专属的sftp目录实现。

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

第 8 页

SFTP交换节点人力资源管理系统本科教务管理系统资产系统sftp目录研究生管理系统机构.dat人事系统sftp目录教务系统sftp目录科研系统sftp目录财务系统sftp目录消费.dat人事.dat机构.dat学生.dat科研管理系统上传其他业务系统下载

2.2.2. 数据库物理架构

交换平台提供数据库交换节点供业务写入数据和读取数据，交换节点为每个业务系统分配一个账号。管理员或提供方建立资源后，交换平台会在交换节点机建立供业务系统写入的表，表名定义为 源系统ID_资源代码。供数给业务系统时，交换平台会把数据写入交换节点机，表名定义为源系统ID_资源代码_需求方系统ID。

第 9 页

交换节点数据库RSXT_JZG_INFO系统1平台采集交换库RSXT_JZG_INFOJWXT_KCB平台供数JWXT_KCB系统2RSXT_JZG_INFO_JWXT系统3JWXT_KCB_RSXT

2.3. 数据交换方式

数据交换方式分为三种：文件，数据库，web服务。他们是资源的承载方式，在资源管理系统上注册资源的时候，可以指定其中一种方式。

2.3.1. 文件方式交换

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

件

? 数据文件每一行的数据表示数据库中一行数据，使用unix换行符换行； ? 文件不包含表头的字段名； ? 字段之间使用 16进制 0X1B 间隔；

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

编码；

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

第 10 页

? 不需要文本限定符，即字段不需要使用引号包含起来； ? 日期字段格式需格式化为yyyy-MM-dd；

? 时间字段格式需格式化为yyyy-MM-dd HH:mm:ss； ? 文件数据编码为UTF-8

? 在数据原有的字段后面新增三个字段：（1）数据新增、删除、修改标识：

A：新增；D：删除；U：修改. （2）数据日期标识：标识数据日期yyyyMMdd或yyyyMMddHHmm.(3)时间戳

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

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

3、文件中数据不能含有换行符，如有换行符和制表符，需要直接删除，或替换为
,换行符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目

第 11 页

录，syroot为业务系统sftp登录后/files目录。下文“xxx”，在单一资源时为资源代码，在复合资源时为报文中定义的文件名。 （一）实时/通报模式文件（B001接口，H001接口）：

1. 数据提供方上传文件路径为：syroot/数据提供方id_xxx.dat，syroot/

数据提供方id_xxx.ok；

2. 数据需求方文件路径为：syroot/数据提供方id_xxx.dat,syroot/数据

提供方id_xxx.ok。

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

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. 时、分频率文件命名：

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

id_xxx_HHMM.dat, syroot/yyyyMMdd/数据提供方id_xxx_HHMM.ok； b. 数据需求方文件路径为：syroot/yyyyMMdd/数据提供方

id_xxx_HHMM.dat 和id_xxx_HHMM.ok。

syroot/yyyyMMdd/数据提供方

2.3.2. 数据库方式交换

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

A-新增，U-修改，D-删除

第 12 页

? dc_dcDataDate varchar(12) 数据日期，更新数据频率大于等于1天时，

格式为YYYYMMDD，更新频率小于1天时，格式为YYYYMMDDHHMM，详解1.7

? dc_dcTimeStamp timestamp 时间戳

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

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

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

的数据。

? 增量供数时，第一个批次写入全量数据，三个控制字段必须写入数据 ? dc_dcFieldAUD=A ? dc_dcDataDate=批次日期 ? dc_dcTimeStamp=写入时间

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

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

2.3.3. WEB服务方式交换

数据提供方实现了C001接口服务（参见接口编码），可以通过此服务对外提供数据服务功能。此中方式较为灵活，数据需求方可在请求中指定条件，能够获取到更为准确的数据。适合数据量较少，实时性较高的场景。

2.4. 系统接入方式

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

系统接入流程 1、

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

第 13 页

2、 3、 4、

数据管理员审批通过后，分配系统ID（系统ID需统一规划） 业务系统提交系统公钥（使用平台秘钥工具产生），数据管理员 数据管理员录入提交的公钥和环境信息

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

1、

数据提供方：

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

2、

数据需求方：

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

3. 数据交换模式

完成一次数据交换，需线上和线下共同配合，具体步骤如下 1、 管理员在资源管理WEB平台新建接入系统的用户 2、 管理员维护提供方或需求方公钥和实时接口的访问地址

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

据结构，更新频率等

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

新建数据库表，供提供方写入数据

5、 审核通过的资源即为有效资源，需提供方按照新建资源时设定的频率写

入数据（数据库表或文件） 6、 管理员对全校发布资源

7、 数据需求方线上提交资源需求申请（三种模式：实时，轮询，通报） 8、 数据提供方完成资源授权，完成审批流程 9、 数据提供方审批完成后，可进行数据交换

a) 实时模式：接收需求方或提供方的消息报文请求，根据不同消息报

文处理实时数据交换

b) 轮询模式：交换平台按照设定的频率读取数据提供方的数据（文件

第 14 页

或数据库表），并把数据供给数据需求方（文件或数据库），如需求方提供的数据库环境，则平台在供数前会建立数据库表，表名请参见2.2.2 c) 通报模式：平台接收到数据提供方的K001（参见4.3.10）通知后，会读取更新的数据，推送给有需求的数据需求方 3.1. 实时交换 2.1.1. 数据报文请求 数据报文请求流程图数据需求方数据交换平台数据提供方请求报文C001安全验证反馈请求失败不存在判断资源目录存在判断资源提供方式报文是否请求报文C001安全验证数据库查询数据是否使用中心库数据否数据是否在中心库是平台返回数据文件到数据需求方返回数据给平台解析数据数据报文 数据报文请求流程图 数据报文请求采用同步方式，数据可由数据提供方提供，也可以由数据库交换节点提供。具体情况如下： 1. 当数据未入中心交换节点数据库，或数据已入中心交换节点数据库，但请求报文时要求数据提供方提供数据，由数据提供方提供C001服务或平台查询交换节点提供方数据库表。数据交换平台获取数据提供方数据的方式以资源 第 15 页

目录定义为准，数据提供方需实现C001数据报文请求服务，提供服务的方式请参见附录2。

数据请求方数据交换平台数据提供方数据请求C001安全验证数据请求C001安全验证数据返回数据返回

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

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

第 16 页

数据请求方数据交换平台数据请求C001安全验证数据返回

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

第 17 页

2.1.2. 数据文件请求 数据文件请求流程图数据需求方数据交换平台数据提供方请求文件B001安全验证反馈请求失败不存在判断资源目录存在数据库方式B001返回报文数据是否在中心库否判断资源提供方式文件方式查询源数据B003-请求文件结果查询可随时发起是B001返回报文请求文件B001指定needNotice=Y安全验证B001返回报文B001返回报文平台落数到数据需求方专属FTP目录上传文件到数据提供方专属FTP目录等待接收B002数据请求方是否需要通知，B001的needNotice是解析文件平台发送B002报文到数据需求方扫描OK文件否根据B001的needNotice判断是否发送通知是平台建立链接文件到数据需求方专属FTP目录发送B002报文到平台 数据文件请求流程图 1. 数据未入中心交换节点数据库：数据文件请求采用异步方式，B001响应报文成功并不表示文件已生成。对于未采集到中心库的数据，由数据提供方提供文件或平台查询交换节点提供方数据库表。数据交换平台获取数据提供方数据的方式以资源目录定义为准，数据提供方需要提供B001和B002服务，提供服务的方式请参见附录2。

第 18 页

数据请求方数据交换平台数据提供方数据请求B001安全验证数据请求B001报文响应报文响应安全验证文件准备文件完成通知B002文件完成通知B002下载文件报文响应报文响应

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

2. 数据已入中心库：数据文件请求采用异步方式，对于已采集到中心交换节点

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

(1) 为保证让数据请求方及时获取数据，提供平台通知的方式。

第 19 页

数据请求方数据交换平台数据请求B001安全验证报文响应文件准备文件完成通知B002下载文件报文响应

数据文件请求——平台提供数据并通知请求方

(2) 为减轻关联系统的开发压力和提高快速部署能力，数据需求方可通过查询

方式或扫描OK文件获取文件是否已提供。

第 20 页

数据请求方数据交换平台数据请求B001安全验证报文响应文件准备请求文件结果查询B003下载文件报文响应

数据文件请求——平台提供数据，数据请求方主动查询

第 21 页

2.1.3. 数据报文推送 数据报文推送流程图数据提供方数据交换平台数据需求方报文数据推送I001安全验证反馈请求失败不存在判断资源目录存在报文数据推送I001数据报文安全验证及数据处理 数据报文推送流程图 数据报文推送指的是数据提供方通过报文的方式主动将数据推送给数据接收方，此模式适用于数据变更后及时通知数据接收方的场景。如下图。 数据提供方数据交换平台数据需求方数据报文推送I001安全验证数据报文推送I001报文响应报文响应 数据报文推送

第 22 页

2.1.4. 数据文件推送

数据文件推送流程图

数据文件推送指的是数据文件提供方上传文件到sftp目录后，主动通知数据文件需求方获取文件。其中资源提供方式为文件。如下图。

第 23 页

数据文件推送

3.2. 轮询交换（固定周期）

数据的采集可通过以下两种方式：

(1) 交换平台采集数据提供方上传到交换节点sftp服务器的文件 (2) 交换平台采集数据提供方在数据交换节点的数据库表；

第 24 页

轮询交换（固定周期推送）采集请求流程图数据需求方数据交换平台数据提供方开始定期采集数据采集方式数据库文件定期扫描OK文件E001-供数据库查询可随时发起查询数据提供方数据库解析文件/报文/数据入库定期供数写入数据需求方数据库数据库供数方式D001-采集情况查询可随时发起文件生成文件到数据需求方专属FTP目录数据订阅采集请求定期扫描OK文件，解析文件 3.2.1. 采集过程 1. 文件采集：（1）数据提供方定期提供数据dat文件和ok文件，平台主动扫描ok文件。如文件存在在处理文件数据。

第 25 页

数据提供方数据交换平台文件上传ftp服务器文件扫描文件入库采集情况查询D001报文响应

文件采集——平台主动扫描

2. 数据库采集：数据采集时，平台查询数据提供方的数据库。数据提供方可以

随时查询数据采集情况。

数据提供方数据交换平台采集情况查询D001报文响应

数据库采集

第 26 页

3.2.2. 供数过程

1. 文件供数：数据需求方成功申请资源轮询交换后，若数据需求方提供环境为

文件交换节点，数据交换平台按照约定的频率从数据提供方采集数据并推送数据文件到数据需求方专属的sftp目录。 数据需求方需扫描ok文件确定文件是否已提供。

需求方处理完文件后，需要通过E002接口反馈处理数据的结果

数据需求方数据交换平台推送文件文件扫描处理E002反馈

文件供数

2. 数据库供数：数据需求方成功申请资源轮询交换后，若数据需求方提供环境

为数据库交换节点，平台则可以将数据直接写入需求方交换节点的数据库表。

需求方处理完文件后，需要通过E002接口反馈处理数据的结果

第 27 页

数据需求方数据交换平台供数据库情况查询E001数据库供数E001响应处理数据E002需求方获取数据反馈E002响应

数据库供数

3.3. 通报交换（不定周期）

数据发送变更后，数据提供方通知平台，平台把更新的数据推送给有需要的需求方。此方式由K001和K002实现。需求方需实现K001服务，提供方需实现K002服务。

资源为文件方式时，文件名从K001报文中获取，sftp路径为sftp根目录 资源为数据库方式时，数据从资源定义的数据库表中获取，供给数据需求方也是数据库表，表名为：提供方系统ID_源系统表名_需求方系统ID

注：1、当有多个需求方时提供方会接收多个需求方的K002报文。 2、数据需求方对一个资源只能选取以上轮询交换和通报交换的一种。

第 28 页

数据更新推送流程图数据提供方新数据写入中间库或生成文件数据交换平台数据接收方文件推送通知K001安全验证反馈请求失败不存在判断资源目录文件建立链接文件数据库获取数据写入需求方数据库安全验证及检查文件或数据库文件推送通知K001解析数据平台返回数据文件到数据需求方K002-接收方更新数据通知反馈

第 29 页

4. 接口设计 4.1. 接口总体说明

4.1.1. 通信模式

? 交换平台对外提供web服务，并提供API供关联方调用； ? 报文编码UTF-8；

? 数据采用json格式化数据。

4.1.2. 安全控制

平台安全控制如下：

1. 平台接入需审核。系统运行后，需要接入平台的业务系统需填写接

入申请；

2. 通信双方线下交换公钥，消息发起方使用私钥加密，消息接受方使

用公钥解密，确保信息发送方为真实的、通过审核的发送方； 3. 使用nonce防止消息重复重放；

4. 字段级授权：如条件共享字段，需要控制不能提供给未授权需求方。

4.1.3. 错误处理

明确处理结果，返回消息中errCode必填，确保消息请求方可以采用对应的措施。

第 30 页

4.2. 消息定义

4.2.1. 消息体

消息体为各方通信报文的承载方式，即每次交互的数据格式都是按照消息体定义的格式填写，字段类型和顺序需保持一致，不同的接口仅仅是data字段格式不同。

字段名称 字段类型 是否必填 说明 发起方流水号，具有唯一性，每次通信都不一样，规则：4位发起方系统ID+14位时间yyyyMMddHHmmss+4位流水号 reqSerialNum String 是 correlationSerialNum String 关联流水号，为平台在收到一个交易多次交互中第一笔流水时生成。 在一个交易多次通信中唯一。 如数据需求方发B001,平台会生成否（返回假设为X，平台返回B001信息会时必填） 填入，同时请求数据提供方时B002也会填入。 B002和B003的关联流水号也必须填入X，以便关联出B001请求。 是 是 接口编码，由平台统一分配，4位 消息发起方系统ID，由平台统一分配，4位 接收消息的系统ID。如果仅仅发给交换平台则填入交换平台系统ID，其他填入关联系统ID。如B001填入资源提供方系统ID，B003填入交换平台的系统ID 消息时间戳 签名域，使用私钥对流水reqSerialNum签名，确定请求方真实有效，见附录公钥私钥使用说明 time+reqSerialNum+请求方mac取hash，防止重放 msgCode msgFromSysID String String msgToSysID String 是 time timestamp 是 sign String 是 nonce String 是

第 31 页

errCode errMsg data String String 错误码：返回信息填写； 否（返回0：成功； 必填） 其他见附录1 否 错误消息 业务数据，请求或返回数据，具体接口见接口详细说明 json格式否 字符

4.2.2. 系统ID（系统编码）

由信息办统一规划的4位系统ID。 系统中文名称 人事系统 教务系统 研究生管理系统 科管系统 校园卡系统 财务信息系统 NetID系统 资产管理系统 学工系统 党务系统 统战系统 数据交换平台 合同管理系统 系统编码（ID） RSXT JWXT YJSG KGXT XYKX 核算中心 CWXX NETI ZCGL XGXT DWXT TZXT SJJH HTXT 网络中心 财务处 学生处 组织部 统战部 发展规划办 人事处 教务部 研究生院 科研院 系统所属部门

4.2.3. 接口编码

接口编码（msgCode）为平台统一分配，每个业务分配一个4位接口编码。

第 32 页

消息类别分为：A-资源目录管理、B-数据文件请求、C-数据报文请求、D-数据采集服务、E-供数服务、F-点对点供数、H-文件推送模式、I-辅助消息。

数据需求方实现 平台实现 数据提供方实现 ? ? ? 消息类别 接口编码 接口名称 说明 A-资源目录管理 A001 资源目录查询 B-数据文件请求 B001 请求文件 B-数据文件请求 B002 实时报文数据 单次文件准备完成通? ? 知 ? B-数据文件请求 B003 请求文件结果查询 C-数据报文请求 C001 数据报文请求 D-数据采集服务 D001 文件采集情况查询 E-供数服务 E-供数服务 E001 ? ? ? ? ? ? 点对点供数，未通F-点对点供数 过交换中心数据传输信息收集 ? ? 提供方上传文件H-数据文件推送 H001 提供方数据文件推送 后，主动推动 ? ? 数据文件提供方主数据需求方数据文件动推送，数据接收H-数据文件推送 H002 接收通知 方异步反馈文件接收完成情况 ? ? 提供方主动推送数I-数据报文推送 I001 提供方数据报文推送 据报文 轮询交换供数据库查 询接口 轮询交换需求方获取 E002 数据反馈 F001 点对点供数信息收集

第 33 页

J-辅助消息 J001 辅助消息 ? ? ? 在数据交换过程中，数据提供方和数据接收方需通过平台转发的辅助交换过程的其他消息，data内容不定由通信双发协商 ? 数据提供方实现 J-辅助消息 J002 服务检查接口 ? ? K-数据更新 K001 资源数据更新推送通知 K-数据更新 K002 资源数据更新接收通知 ? ?

4.3. 接口详细设计

就每个接口而言，报文中的data格式是不同的。因此，下文将详细规范每个接口中业务数据data的格式。

4.3.1. 资源目录管理 4.3.1.1. A001—资源目录查询

资源目录查询支持根据资源ID精确查询，也可分页查询。只有数据管理员发布的资源才可以被查询。

第 34 页

资源目录为平台的核心信息，所有接入方通信都必须定义资源目录，平台会判断资源目录是否存在，是否授权来确定交换请求是否处理。资源目录的核心信息有资源ID、代码、类别，获取资源的方式，获取资源的参数，如果是提供轮询交换模式的资源，则还需要提供采集频率和预计完成准备时间等。

当资源定义multiFlag=M时，不提供轮询交换，只能实时交换和通报交换。 不经过交换中心的消息交互和资源交换需要纳入交换中心资源管理，也需定义和提交资源目录，在双方交互完成后，由发起方发送F001接口供交换平台登记。

其中，采集供数频率定义如下： ? ? ? ? ?

minute:30-含义每30分钟运行一次； minute:60-含义每60分钟运行一次； day-含义每日运行一次；

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

month:两位日期-含义每月运行一次，如month:02为每月2日运行；

? year:四位日期-含义一年运行一次，如year:0321为每年3月21日运行；

1) 请求数据 字段名称 resourceID providerSysID page pageSize

2) 返回数据 字段名称 totalSize resultSize page pageSize 字段类型 是否必填 Long Integer Integer Integer 是 是 是 是 总记录数 当前返回记录数 第几页，请求原样返回 每页条数，请求原样返回 说明 字段类型 是否必填 String String Integer Integer 否 否 是 是 资源ID 系统ID 第几页 每页条数，最大2000条 说明

第 35 页

result

3) result 字段名称 resourceID List> 是 见下表 字段类型 String 是否必填 是 资源ID 说明 multiFlag char 是 是否包含多个文件标识： S：单一资源（对应一个文件，一个表）； M：复合资源（可多个文件，多个消息定义为一个资源ID，对应一类资源，一类消息）。 资源代码： （1）当multiFlag=S时： 数据库表为：数据提供方表名, 文件类型为：文件名去掉系统ID和后缀, 报文类型为：返回报文中result中的tablename； （2）当multiFlag=M时： 自定义的这一类资源的类别名称，如果是文件类型，建议使用这一类文件的名称统一前缀。 提交资源是确保本系统唯一。 资源描述 文件类型： （1）结构化数据：S。类似数据库格式化的数据，有字段说明的数据； （2）非结构化数据：N。非结构化数据，如影像文件。 注：非格式化数据平台不处理标识，非结构化数据不入中心库 资源来数据提供方 是否存储进中心库： Y-入中心库，N-不入中心库。 注：数据请求时，如已入中心库，优先从中心库获取数据返回。 resourceAlias String 是 remark String 是 resourceType Char 是 providerSysID String 是 isStore char 是

第 36 页

isAuthorizatichar on 是 对查询系统是否已授权，非资源目录本身的信息，关联授权信息获取。 Y：已授权 N：未授权 frequency String 采集供数频率定义： minute:30 含义每30分钟运行一次； minute:60 含义每60分钟运行一次； day 含义每日运行一次； 否：非采集week:n 含义周几运行，如周一，则n=1； 时可为空 month:两位日期 含义每月运行一次，如month:02为每月2日运行； year:四位日期 含义一年运行一次，如year:0321为每年3月21日运行； 数据提供方完成供数的时间点，格式为否：文件供HH:mm，轮询交换时这个时间作为调度任数必填 务时间。 数据提供方资源承载方式： F：文件方式 D：数据库方式 I：报文方式 M：普通通知类消息（双方直接通讯方式的资源定义） 是否增量：Y-增量、N-全量。 如是增量，中心库需追加；如是全量，中心库需覆盖。 注：如数据提供方有物理删除数据，则不能提供增量供数方式。增量的数据必须包括当期新增和修改的数据（业务上逻辑删除的数据为修改）。 putTime String getMode char 是 isIncrease char 是

第 37 页

increaseParam String 增量抽取sql中where条件后面的内容。如条件中有日期，请使用格式化参数代替，前后加上‘#’ 1、日期使用#yyyyMMdd#或#yyyy-MM-dd# 2、日期时间使用#yyyyMMddHHmmss# 或 #yyyy-MM-dd HH:mm:ss# 否：数据库注：实际执行时日期参数使用具体日期增量抽取的替代，需能够抽取到当期新增和修改的时候必填 数据（业务上逻辑删除的数据为修改） 比如资源定义：lastTime>='#yyyy-MM-dd#' 实际使用时： C001需传入:lastTime>='2017-10-31' 平台采集时：lastTime>='2017-10-31' 是否流水表，流水表只能为增量抽取。 Y-是；N-否 注：流水表不处理增改删标志，默认只有新增。 资源类别： B：基础数据 S：业务数据 D：决策数据 具体定义见附录:资源类别定义 isLogTable char 是 catalog char 是

4.3.2. 数据文件请求模式接口 4.3.2.1. B001—文件请求

数据实时交换通过文件的方式，如涉及条件共享字段且未授权，请数据提供方不要写入文件。当资源数据交换方式为F：文件方式或D：数据库方式时，数据请求方可使用B001请求资源。注意：B001返回报文中correlationSerialNum会作为B002和B003的关联流水号。在B002和B003请求报文中需填入。

服务方需判断needNotice，以确定是否发送B002报文通知。 1) 请求数据

字段名称

字段类型 是否必填 第 38 页

说明

resourceID reqSysID String Stirng 是 是 资源ID 数据请求方系统ID 注：报文体中msgFromSysID经过平台转发后，会改为SJJH increaseParam String 增量抽取的where条件后面的内容，不含否：数据库where，需能够抽取到当期新增和修改的数增量抽取据（业务上逻辑删除的数据为修改）。 的时候必注：参照资源目录定义的increaseParam，填 日期格式化字符串需替换为实际日期值。 是否使用中心库数据，资源为复合资源（multiFlag=M）时无效。 Y使用，N不使用。 默认为使用中心库，如数据未入中心库，该字段无效。 数据需求方是否需要通知:Y-需要，N-不需要 如果填写Y-需要，则需实现B002服务。 平台和数据提供方需判断此标志，确定是否发送B002通知。 数据文件名： （1）当资源为单一资源（multiFlag=S，一个表或一个文件）时，系统ID_资源代码.dat； （2）当资源为复合资源（multiFlag=M）时，交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 标志文件名： （1）当资源为复合资源（multiFlag=S，一个表或一个文件）时，系统ID_资源代码.ok； （2）当资源为复合资源（multiFlag=M）时，交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 isUseStore char 否 needNotice char 是 dataFileName String 否 okFileName String 否

2) 返回数据为空，即返回报文中data无数据，是否成功参见报文errCode字

段。

第 39 页

4.3.2.2. B002-单次文件准备完成通知

文件请求采用异步方式，平台或数据提供方根据B001的needNotice字段判断是否需用使用B002通知文件已生成。

注意，请求报文体中correlationSerialNum需填写平台返回B001报文中的correlationSerialNum；返回报文体中correlationSerialNum需原样返回。文件格式请参见本文档2.3.1数据文件格式定义。 1) 请求数据 字段名称 resourceID status remark 字段类型 是否必填 String char String 是 是 否 资源ID 采集供数状态:D-无需执行，N-未运行，R-运行中，F-完成，E-异常 执行信息 数据文件名： （1） 当资源定义multiFlag=S时： 系统ID_资源代码.dat； （2） 当资源定义multiFlag=M时： 交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 标志文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.ok； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 说明 dataFileName String 否 okFileName String 否

2) 返回数据，报文errCode为0时，反馈文件名称。 字段名称 字段类型 是否必填 说明

第 40 页

dataFileName String 否 数据文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.dat； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 标志文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.ok； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 okFileName String 否

4.3.2.3. B003-请求文件结果查询

请求文件后，数据需求方如不需要平台通知，可在半小时后主动查询文件生成的状态。

注意，请求报文体中correlationSerialNum需填写平台返回B001报文中的correlationSerialNum。返回报文原样返回 1) 请求数据为空 字段名称 resourceID 字段类型 是否必填 String 是 资源ID 数据文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.dat； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 标志文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.ok； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 第 41 页

说明 dataFileName String 否 okFileName String 否

2) 返回数据 字段名称 resourceID status remark 字段类型 String char String 是否必填 是 是 否 资源ID 采集供数状态:D-无需执行，N-未运行，R-运行中，F-完成，E-异常 执行信息 数据文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.dat； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 标志文件名： （1）当资源定义multiFlag=S时：系统ID_资源代码.ok； （2）当资源定义multiFlag=M时：交换双方协商，建议交换双方定义的文件名称带上数据提供方ID，避免文件名重复。 说明 dataFileName String 否 OkFileName String 否

4.3.3. 数据报文请求模式接口 4.3.3.1. C001-数据报文请求

对应数据量较少的数据请求，可采用数据报文请求。数据提供方可提供web服务提供数据，或提供数据库连接方式，平台直接抽取数据。当数据交换方式为I：报文方式或D：数据库方式时，数据请求方可使用C001请求资源。数据报文请求返回数据格式请参见result说明。请数据提供方判断是否有条件共享字段，是否有授权，如无授权，请不要写入条件共享未授权字段 1) 请求数据

第 42 页

字段名称 resourceID 字段类型 是否必填 String 是 资源ID 说明 reqSysID Stirng 是 数据请求方系统ID，平台转发后，数据提供方可获取数据需求方ID。 注：报文体中msgFromSysID经过平台转发后，会改为SJJH increaseParam String 否：数据增量抽取的where条件后面的内容。 库增量抽注：参照资源目录定义的increaseParam，取的时候日期格式化字符串需替换为实际日期值。 必填 是否使用中心库数据，资源定义multiFlag=M时无效。 Y使用，N不使用。 默认为使用中心库，如数据未入中心库，填写Y无效。 第几页 每页条数，最大2000条 isUseStore char 否 page pageSize

Integer Integer 是 是 2) 返回数据 字段名称 resourceID source totalSize resultSize page pageSize result 字段类型 String String Long Integer Integer Integer Map 是否必填 是 是 是 是 是 是 否 资源ID 数据来源系统ID 如果中心库提供数据则为：SJJH 否则填写具体业务系统ID 总记录数 当前返回记录数 第几页，请求原样返回 每页条数，请求原样返回 业务数据内容，包含三块内容tablename，head，content 说明 返回内容中result样例如下 \

第 43 页

\\

] }

[\[\

4.3.4. 数据采集服务接口 4.3.4.1. D001-采集情况查询

对外提供采集情况查询，以便系统进行管理和监控，数据提供方核对数据采集情况。 1) 请求数据 字段名称 resourceID day 字段类型 是否必填 String String 是 是 资源ID 说明 数据日期： 一天多次的格式：yyyyMMddHHmm 其他：yyyyMMdd 2) 返回数据 字段名称 resourceID day 字段类型 String String 是否必填 是 是 资源ID 数据日期： 一天多次的格式：yyyyMMddHHmm 其他：yyyyMMdd 采集供数状态:D-无需执行，N-未运行，R-运行中，F-完成，E-异常 执行信息 说明 status char 是 remark

String 否 第 44 页

4.3.5. 供数服务

4.3.5.1. E001-轮询交换供数据库查询

平台对外提供数据库供数情况查询，以便数据需求方确认数据是否可用。平台实现此接口 1) 请求数据 字段名称 resourceID day

2) 返回数据 字段名称 resourceID day 字段类型 String String 是否必填 是 是 资源ID 数据日期： 一天多次的格式：yyyyMMddHHmm 其他：yyyyMMdd 采集供数状态:D-无需执行，N-未运行，R-运行中，F-完成，E-异常 执行信息 说明 字段类型 是否必填 String String 是 是 资源ID 数据日期： 一天多次的格式：yyyyMMddHHmm 其他：yyyyMMdd 说明 status char 是 remark String 否 4.3.5.2. E002-轮询交换需求方获取数据反馈

需求方通过轮询交换模式获取数据（文件或数据库方式）后，需通过E002接口反馈获取数据的情况 1) 请求数据 字段名称 resourceID 字段类型 是否必填 String 是 资源ID 说明

第 45 页

day totalSize status remark

String int char String 是 是 是 否 数据日期： 一天多次的格式：yyyyMMddHHmm 其他：yyyyMMdd 记录数 F-完成，E-异常 执行情况 2) 返回数据

返回数据为空，即报文中data无数据，是否成功参见报文errCode字段。

4.3.6. 点对点供数

4.3.6.1. F001-点对点供数信息收集

对于已存在的，未通过交换中心的数据交换，不适合迁入数据交换平台或暂无计划迁入数据交换平台的情况，需要数据提供方（服务方）提供数据使用情况给数据平台，方便对数据流向的查询和管理。每次使用数据都需要调用此接口提供数据使用信息。 1) 请求数据 字段名称 resourceID reqSysID providerSysID 字段类型 是否必填 String String String 是 是 是 说明 资源ID，提交消息前需到模型平台注册资源 数据请求方系统ID，由平台统一分配 数据提供方系统ID，由平台统一分配 数据内容中文描述：教职工基本信息，教学信息，科研信息，教职工奖惩信息等 数据补充说明 数据获取/消息时间：yyyy-MM-dd HH:mm:ss 数据量 dataContent remark getTime totalRow String String dataTime Long 否 否 是 否

第 46 页

本文来源：https://www.bwwdw.com/article/imjw.html