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

1、 中山大学数据 共享 交换平台接 入 规范 (试行 ) 中山大学 信息化管理办公室 2018 年 5 月 目 录 1. 概述 . 1 1.1. 读者 . 1 1.2. 目的 . 1 1.3. 相关术语 . 1 1.4. 信息资源目录 . 2 1.5. 数据交换方式 . 5 1.6. 数据交换模式 . 5 1.7. 数据日期概念 . 6 1.8. 增量条件 . 6 2. 交换体系设计 . 7 2.1. 总体设计 . 7 2.2. 架构设计 . 8 2.2.1. SFTP 服务架构 . 8 2.2.2. 数据库物理架构 . 9 2.3. 数据交换方式 . 10 2.3.1. 文件方式 交换 . 1

2、0 2.3.1.1. 轮询交换（固定周期）、通报交换（不固定周期）提供的文件 . 10 2.3.1.2. 实时交换方式提供的文件 . 11 2.3.1.3. 文件路径说明 . 11 2.3.2. 数据库方式交换 . 12 2.3.3. WEB 服务方式交换 . 13 2.4. 系统接入方式 . 13 3. 数据交换模式 . 14 3.1. 实时交换 . 15 2.1.1. 数据报文请求 . 15 2.1.2. 数据文件请求 . 18 2.1.3. 数据报文推送 . 22 2.1.4. 数据文件推送 . 23 3.2. 轮询交换（固定周期） . 24 3.2.1. 采集过程 . 25 3.2.2

3、. 供数过程 . 27 3.3. 通报交换（不定周期） . 28 4. 接口设计 . 30 4.1. 接口总体说明 . 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. 供数服务

4、 . 45 4.3.6. 点对点供数 . 46 4.3.7. 数据文件推送 . 47 4.3.8. 数据报文推送 . 49 4.3.9. 消息通知模式 . 50 4.3.10. 通报交换（不固定周期） . 51 5. 数据权限 . 52 5.1. 资源权限 . 52 5.2. 字段级权限 . 52 6. 附录 1 错误码 . 53 7. 附录 2 web 服务使用说明 . 54 7.1. 使用交换平台的接口 . 54 7.2. 接入方实现的服务 . 56 7.3. 报文样例 . 58 第 1 页 1. 概述 中山 大学 数据 共享 交换平台 （下 称 “ 交换 平台 ” ） 是 负责 传输 校

5、内 不同信息系统间数据 的 平台， 各业务 系统通过 与数据 交换平台 对 接， 实现业务数据在不同业务系统之间顺畅、实时、批量传输。 1.1. 读者 与 交换平台对接的 信息 系统建设方 与 交换平台对接的 信息 系统开发 方 交换 平台开发 方 交换 平台 运维管理 方 1.2. 目的 本文档是中山大学数据 共享 交换平台接口需求及设计方案相关文档，可用于指导 对接 接口 开发、 联调 、 测试工作。 1.3. 相关术语 术语 说明 数据 共享 交换平台 下文如无特殊说明，简称 交换 平台 。 业务系统 需要 实施 数据 共享交换的业务 信息系统 ，如人事信息管理系统、教务信息管理系统等。

6、 ok文件 标志文件，在数据文件生成完成后产生 的空文件 ，供数据需求方判断文件是否可读取 资源代码 资源如果 是 数据库表 ， 则资源代码 为 ： 数据提供方 表名 。 资源 如果是 文件 ,则资源代码 为 ： 文件名去掉系统 ID 和后缀 。 资源 如果是 报文 ，则 资源代码为 ：返回报文中 result中的 tablename。 dcroot 交换平台 sftp 根目 ，实际为登录后的 files 目录 第 2 页 syroot 交换 平台为 每个 业务系统 配置 的 专属 sftp 根目录 。不 同的业务 系统 的 根目录 不同 ，实际为登录后的 files 目录 单一资源 资源目录

7、中一个资源 ID 定义为一个资源，当资源为一个文件或一个表时，为单一资源 复合资源 资源目录中一个资源 ID 定义为一个资源，当资源为一类资源，即对应多个文件或多个消息时，为复合资源 。 例如 一份完整档案， 包含 多个 不同 类型 文件 集合 ，此集合属于一个 复合 资源。 1.4. 信息 资源目录 信息 资源 目录为数据 共享 交换的 依据 ， 目录 所含 内容既 是对 共享 信息资源 的描述 ，也是数据 交换 关系的描述。 在数据 共享交换 中 的 一张数据库表 、 一个文件或 一 类 文件 都 是 属于 信息资源 ， 注册于信 息资源目录中 。 中山 大学信息 资源目录 由 数据模型

8、管理 平台 管理 ， 数据 共享交换实施前 需要数据提供方 注册 ，并由数据管理员审核通过后对全校发布。 下表详细介绍资源的属性 字段名称 字段类型 是否必填 说明 resourceID String 是 资源 ID， 一个资源的 唯一 ID multiFlag char 是 是否包含多个文件标识： S：单一资源（对应一个文件，一个表）； M：复合资源（可多个文件，多个消息定义为一个资源 ID，对应一类资源，一类消息）。 第 3 页 resourceAlias String 是 资源代码 ： （ 1）当 multiFlag=S 时 ： 数据库表为： 数据提供方 表名 , 文件类型为：文件名去掉

9、系统 ID和后缀 , 报文类型为：返回报文中 result 中的tablename； （ 2）当 multiFlag=M 时 ： 自定义的这一类资源的类别名称，如果是文件类型，建议使用这一类文件的名称统一前缀。 提交资源是确保本系统唯一。 注 ： 受限于 oracle 对表名的限制， 时分频率 供 数 时 表 名 为 providerSysID_ resourceAlias_ reqSysID，资源代码最长只能为 22位； remark String 是 资源描述 resourceType Char 是 是否结构化数据 ： （ 1）结构化数据： S。类似数据库格式化的数据，有字段说明的数据；

10、（ 2）非结构化数据： N。非结构化数据，如 图片 文件。 providerSysID String 是 数据提供方 ID。 见 3.2.2 系统 ID 章节 isStore char 是 数据 是否 在中心 交换节点留存 ： Y-代表 数据 在交换 过程中会在中心节点留存 ， 即数据交换过程中数据会 在 交换平台 “ 落地 ”； N-代表 数据 在 交换过程中 不在 中心节点留存，即数据交换过程中数据 只 交换，但不会 在 交换平台 “ 落地 ” 。 frequency String 否：非 定时数据 交换方式 可为空 数据交换 任务 定时启动的 频率定义： minute:30 含义 是交换

11、任务从 每日 0点起 每 30 分钟运行一次； minute:60 含义 是交换 任务从每日 0点起 每 60 分钟运行一次； day 含义 每日 运行一次； week:n 含义周几运行，如周一，则 n=1； month:两位日期 含义每月运行一次，如 month:02 为每月 2 日运行； year:四位日期 含义一年运行一次， 如year:0321 为每年 3月 21 日运行； 第 4 页 putTime String 否： 数据提供方完成供数的时间点，格式为HH:mm， 此 字段与 frequency 结合使用 ，用于 表述某天 某日 定时数据 交换的时间。 例如 ： getMode c

12、har 是 数据提供方 资源承载方式： F：文件方式 D：数据库方式 I：报文方式 M：普通通知类消息（双方直接通讯方式的资源定义） isIncrease char 否 是否增量： Y-增量、 N-全量。 如是增量，中心库需追加；如是全量，中心库需覆盖。 注：如 数据提供方 有物理删除数据， 需要写入 交换节点 机并打 D 标识。增量的数据必须包括 当期新增、 修改 、删除 的数据（业务上逻辑删除的数据为修改）。新建业务系统必须提供增量供数模式，不再接受全量供数模式 increaseParam String 否：数据库增量抽取的时候必填 增量抽取 sql中 where条件后面的内容。如条件中有

13、 数据 日期，请使用格式化参数代替 ，前后加上 # 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

14、(2017-10-31,yyyy-mm-dd) 注：数据日期说明见 1.7，与实际运行日期不同 isLogTable char 是 是否流水表，流水表只能为增量抽取。 Y-是； N-否 注：流水 表不处理增改删标志，默认只有新增。 第 5 页 catalog char 是 资源类别： B-基础数据 S-业务数据 C-决策数据 具体定义见附录 :资源类别定义 theme string 是 所属主题 教职工域 教学域 财务域 学生业务域 科研域 1.5. 数据 交换 方式 1. 数据库 方式 ：数据 供需双方 可 通过读写交换 节点 上 数据库的表 或视图实现 数据交换 。 2. 文件 方式 ：数

15、据 供需双方 可通过 读写交换 节点上的 文件 实现 数据交换 ，如是结构化数据，需要按照接口文档中描述的文件格式提供文件， 以 便于交换 平台 对文件解析。 3. web 服务 方式 ：数据 供需双方 可 通过 提供 webservice 对提供 和 获取 数据，webservice需按照接口文档中的描述方式实现，为 http post方式的 RESTful方式，参数为 Json 格式，即需 按 C001 接口 实现 。 详见 4.3.3 章节 。 1.6. 数据交换 模式 1. 实时 交换 ： 通过 B001 ， C001， H001， I001 等接口请求的数据，会实时返回或生成数据。

16、2. 轮询 交换（ 固定周期 ） ： 此 方式下， 数据 提供方或者数据 需求 方 在 资源目录中 约 定数据交换 频率（如 30分钟一次 、 1 日一次 等 ） ， 并 按照该频率，数据提供 方提供数据到 交换平台 ，数据 需求 方定期 从 交换 平台轮询 获取数据 。此方式 下，交换平台不会主动 告知 各方 是否 有 更新 数据 ， 需要 数据需求 方定期轮询 。 3. 通 报 交换（ 不定周期 ） ： 此 方式下， 业务数据 数据 发生 变更后， 数据 提供方即时 主动 通报 数据 交换平台 ，由数据交换平台把数据推送给 数据 需求方 ，同第 6 页 时 通 报 数据 需求方 从交换 平

17、台 获取 数据 。此种交换方式频率不固定。 1.7. 数据日期概念 ， 提供方生成文件需要加上数据日期，文件命名和 要 加 上数据日期，即下文中 yyyyMMdd 和 yyyyMMddHHmm，数据日期与实际运行日期是有区别的，实际处理数据是上一期 （配合增量条件） 的数据，所以数据日期 =实际日期 -周期 。 采用 数据 库交换方式时， 交换 平台 会 在交换表中建时间戳 内建字段 。 下面给出具体的例子 周期 运行日期 /时间 数据日期 /时间 说明 minute:30 201803291130 201803291100 半点和整点运行 minute:60 201803291100 201

18、803291000 整点运行 day 20180329 20180328 每天运行 week:5 20180406 20180326 （上周周一） 每周五运行 month:01 20180402 20140301 （上月 1日） 每月 1日运行 year:0301 20180301 20170101 （上年元旦） 每年 3月 1日运行 1.8. 增量条件 数据提供 方 提供数据 可以是增量也可以是全量， 原则 要求初次提供全量数据，日常提供 提供增量数据。 为了 保证 交换平台 的数据与源系统 数据 语义 一致， 业务 系统 发生数据新增、修改、删除数据的操作， 都 应按照增量方式把数据提交给交换平台 。数据 增加标 识字段 为 A，数据 修改的标志位为 U，数据删除标 识 位 为 D，后续章节将具体介绍 。 增量 条件中日期部分 ，请使用格式化参数代替，前后加上 # 字符 1、日期使用 #yyyyMMdd#或 #yyyy-MM-dd#