1、 1 厦门大学实验室资源信息管理系统 接口说明文档 1 系统概述 厦门大学实验室资源信息管理系统，以下简称“校级平台”，各院级实验仪器管理系统，以下简称“院级系统”。管理单位可以按照统一的数据标准及格式规范，通过接口的方式将报送数据至校级平台。 本接口采用 REST 接口方式，提交 与返回的 数据为 JSON 格式，以实现校级平台与各院级系统在数据与服务方面的对接，更加有效地开展实验室资源信息管理服务。 本规范适用于各院级系统。 校级平台与院级系统共涉及 4 个接口，具体如下： 接口名称 用途 预约请求接口 接收校级平台推送的用 户预约请求，返回仪器预约页面 仪器数据获取接口 接收校级平台推送
2、的仪器信息 仪器数据报送接口 接收院级系统向校级平台推送仪器信息 使用记录上报接口 接收院级系统向校级平台推送仪器使用记录接口 用户信息接口 用于院级系统与校级用户统一认证和管理 2 接口说明 2.1 预约请求接口 2.1.1 接口描述：校级平台通过该接口将预约请求推至院级系统，获取相应院级系统返回的仪器预约页面。 2.1.2 请求消息参数描述 参数名称 类型 是否为空 描述 innerID String 否 仪器所属单位内部的唯一编码； insCode String 否 管理单位的唯一标识； 2.1.3 响应消息参数描述 参数名称 类型 是否为空 描述 2 页面的地址（ url） Strin
3、g 否 仪器预约页面的 url 2.1.4 接口流程 （ 1） 校 级系统发布预约仪器服务； （ 2） 用户点击预约按钮，接口将用户的预约请求（仪器所属单位内部编码innerID 及单位唯一标识）送至相应的院级系统； （ 3） 院级系统接收到校级平台推送的预约请求，通过在线平台的预约审核流程对预约请求进行审核，根据审核结果并返回具体的仪器预约页面； （ 4） 用户可以在院级系统返回的预约页面中进行仪器 预约操作。 2.1.5 注意事项 （ 1） 校级平台统一分配院级单位的唯一标识； （ 2） 校级平台不提供仪器预约服务，只能将用户预约请求推送至院级系统，由院级系统提供具体的仪器预约服务； （
4、3） 院级系统返回给校级平台的是具体的仪器与预约页面 url，而不是院级系统的首页或其他页面，并且确保预约页面能打开； （ 4） 院级系统返回的预约页面中必须包括该仪器的开放日历及机时安排情况； 2.2 仪器数据获取接口 2.2.1 接口描述：院级系统获取校级平台仪器数据的接口。 2.2.2 请求消息参数描述 参数名称 类型 是否为空 描述 insCode String 否 院级单位的唯一标识 instruType int 否 填报数据类型： 9 仪器信息 2.2.3 响应消息参数描述 参数名称 类型 是否为空 描述 状态码 int 否 仪器数据推送结果： 100 代表成功 101 代表数据存
5、取成功，并根据结果提3 示信息 200 代表单位编码错误 201 代表填报数据类型错误 202 代表推送的数据 json 字符串格式错误 203 代表验证数据格式错误 204 代表其他异常 301 代表数据库操作异常 仪器数据集合 List 否 见 2.2.3 返回示例说明 2.2.3 返回示例说明 “status“:100, “list“: “CollegeName“:“xxxx“,/学院名称 “UnitNumber“:“2J02“,/单位号 “SASACClassificationNum“:“2400502“,/国资分类号 “InstrumentChineseName“:“xxxx“,/仪
6、器名称 (中文 ) “InstrumentClassificationNumber“:“03052207“,/仪器分类号 “Model“:“MCR302“,/型号 “Specifications“:“MCR302“,/规格 “UnitPrice“:“597916.07“,/单价 “DateOfProduction“:“2013/12/6 0:00:00“,/出厂日期 “PurchaseDate“:“2013/12/6 0:00:00“,/购置日期 “StorageTime“:“2014/11/25 0:00:00“,/入库时间 “CountryOfOrigin“:“xxxx“,/生产国别 “C
7、ountryCode“:“156“,/国别码 “Manufacturer“:“xxxx“/生产厂家 4 2.3 仪器数据报送接口 2.3.1 接口描述：院级系统上报校级平台仪器数据的接口。 2.3.2 请求消息参数描述 参数名称 类型 是否为空 描述 insCode String 否 院级单位的唯一标识 instruType int 否 填报数据类型： 9 仪器信息 仪器数据集合 List 否 见 仪器数据集合字段说明 仪器数据集合字段说明 参数名称 是否必填 参数说明 示例参考 isCourtyardNew 是 是否院级新增仪 器 0 为否 1 为是 CollegeName 是 学院名称 U
8、nitNumber 是 单位号 SASACClassificationNum 是 国资分类号 InstrumentChineseName 是 仪器名称（中文） InstrumentClassificationNumber 是 仪器分类号 Model 是 型号 Specifications 是 规格 UnitPrice 是 单价 DateOfProduction 是 出厂日期 PurchaseDate 是 购置日 期 StorageTime 是 入库时间 CountryOfOrigin 是 生产国别 5 CountryCode 是 国别码 Manufacturer 是 生产厂家 Instrume
9、ntSharingCode 是 仪器共享分类编码 FundsNardNumber 是 经费卡号 MainTechnicalIndex 是 主要技术指标 MajorFundingSources 是 主要经费来源 MainTestResearchArea 是 主要测试研究领域与代码 FunctionalFeatures 是 功能特色 SharedMode 是 共享模式 OneYearOffCampusOpen 是 一年内可用于对校外开放机时 MeasurementCertification 是 是否通过计量认证 PlacePosition 是 放置位置 InstrumentImage 是 仪器图片
10、 InstrumentResponsiblePerson 是 仪器负责人 InstrumentResponsiblePersonTel 是 仪器负责人联系电话 InstrumentResponsiblePersonMail 是 仪器负责人电子邮箱 InstrumentEinglishName 否 仪器名称 (英文 ) 2.3.3 响应消息参数描述 参数名称 类型 是否为空 描述 状态码 int 否 仪器数据推送结果： 100 代表成功 101 代表数据存取成功，并根据结果提示信息 200 代表单位编码错误 201 代表填报数据类型错误 202 代表推送的数据 json 字符串格式6 错误 20
11、3 代表验证数据格式错误 204 代表其他异常 301 代表数据库操作异常 2.3.4 接口流程 （ 1） 校 级平台发布仪器数据报送服务； （ 2） 院级系统通过该接口推送仪器数据至校级平台； （ 3） 校级平台验证单位唯一标识和仪器类别的正确性；验证失败则返回相应状态码； （ 4） 校级平台对上报的仪器数据进行验证，验证通过进行数据库存储，已报过的数据则进行更新；验证失败返回相应状态码； 2.2.5 注意事项 （ 1） 院级系统通过接口报送的数据格式按照附录 1 中仪器数据报送接口的各类型仪器示例。 （ 2） 校级平台统一分配院级单位的唯一标识；院级单位可登录校级平台查看本单位的唯一标识，
12、院级系统需保存单位标识关联表； （ 3） 管理单位院级系统需将平台负责人的通讯邮箱上报校级 平台；校级平台对数据验证的错误信息会以邮件的方式发送院级系统负责人的邮箱； （ 4） 院级系统接与校级平台的对接过程中，如果多次出现错误状态码，及时联系相关人员。 2.4 仪器使用记录接口 2.4.1 接口描述：院级系统将仪器使用记录数据上报到校级平台的接口。 2.4.2 请求消息参数描述 参数名称 类型 是否为空 描述 insCode String 否 院级系统的唯一标识 使用记录的集合 List 否 详见使用记录的集合字段说明 使用记录的集合字段说明 参数名称 是否必填 参数说明 示例参考 7 Ap
13、pointmentStart 是 预约时间（起） 2013/12/6 0:00:00 AppointmentEnd 是 预约时间（止） 2013/12/6 0:00:00 AppointmentLength 是 预约时长 ControllerRecordStart 是 控制器记录时间（起） 2013/12/6 0:00:00 ControllerRecordEnd 是 控制器记录时间（止） 2013/12/6 0:00:00 ControllerRecordLength 是 控制器记录的实际测试时长 SampleNumber 否 样品个数 SendSampleName 是 预约或送样人姓名 S
14、endSampleNumber 是 预约或送样人教工号（学工号） SendSampleGroup 是 预约或送样人所属课题组 SendSampleGroupHead 是 预约或送样人所属课题组负责人 CardPersonName 是 刷卡人姓名 CardPersonNumber 是 刷卡人教工号（学工号） CardPersonGroup 是 刷卡人所属课题组 OrderItemName 否 预约检测项目名称 SendSampleItemName 否 送样检测项目名称 2.4.3 响应消息参数描述 参数名称 类型 是否为空 描述 状态码 int 否 服务成效数据推送结果： 100 代表成功 20
15、0 代表单位编码错误 201 代表推送的数据 json 字符串格式错误 202 代表数据验证错误 203 代表其他异常 301 代表数据库操作异常 8 2.4.4 接口流程 （ 1） 校级贵重仪器设备管 理系统根据从各学院抓取的仪器设备使用情况数据作为计费数量的依据 ； （ 2） 院级系统调用该接口将 单位的 仪器设备使用情况 数据推送至校级平台； （ 3） 校级平台首先验证单位唯一标识的正确性，验证通过则获取 仪器设备使用情况 数据；验证失败则返回相应的状态码； （ 4） 校级平台将上报的 仪器设备使用情况 数据进行验证，验证通过则保存到数据库中，验证失败则返回相应的状态码； 2.3.5 注
16、意事项 （ 1） 院级系统通过该接口报送的 仪器设备使用情况 数据按照附录 1 中的 仪器使用记录 接口的示例。 （ 2） 校级平台 统一分配 院级单位 的唯一标识；院级系统需保存单位标识关联表； 院级 单位可登录校级平台查看本单位的唯一标识； （ 3） 院级系统需将平台负责人的通讯邮箱地址上报 校级 平 台； 校级平台 对数据的验证错误信息会以邮件的方式发送院级系统负责人的邮箱； （ 4） 院级系统接与校级平台的对接过程中，如果多次出现错误的状态码，需联系相关人员。 2.5 用户信息接口 校级平台提供用户信息接口，用于院级系统与 校级 平台的用户统一认证和管理。具体详情见 Oauth 说明文
17、档。 9 对接用户认证开发指南 一、 Oauth2.0 授权访问流程 获取用户信息重定向用户到 a u t h o r i z e接口生成 a u t h o r i z e _ c o d e ，重定向用户到r e d i r e c t _ u r i使用 a u t h o r i z e _ c o d e 向a c c e s s _ t o k e n 接口发起请求生成 a c c e s s _ t o k e n ， 并返回使用 a c c e s s _ t o k e n 向r e s o u r c e 接口发起请求返回用户信息OAuth 客户端 OAuth 服务器（ 1
18、） 管理单位网站重定向用户到 校级 平台提供的 authorize 接口 ，如果用户同意授权，校级 平台会把用户重定向回到 院级 单位 网站，并附上授权码 authorize_code； （ 2） 校级 单位网站使用 authorize_code 向 校级 平台的 access_token 接口发起请求， 校级 平台在验证请求合法后，会返回访问令牌 access_token； （ 3） 校级 单位网站 使用 access_token 向 resource 接口发起请求 ， 获取用户信息 。 二、 单位平台工作 流程 1. 用户 在 校级 平台 发起 “预约 仪器 ”请求 ， 校级 平台将请求重
19、定向到 院级 平台。 2. 院级 平台 检查用户登录状态，若是登录状态，则直接 转到仪器 预约页面；若 处于 未登录状态 ，则转到 步骤 3 代表 的登录页面 。 3. 单位平台 的 登录 页面 中 要有 “使用 校级 平台账号 登录 ”入口。 4. 若 用户选择直接使用 院级 平台账号登录，则 登陆后 转到 仪器 预约页面 ； 若用户选择 “使10 用 校级 平台账号登录 ”，则 开始 oauth2.0 授权认证 过程。 5. 重定向 用户到 校级 平台 authorize 接口 ，请求 authorize_code。校级平台 authorize 接口 访问标准如下 ： 1) URL htt
20、ps:/mainplatform/oauth2/authorize 2) HTTP 请求方式 GET/POST 3) 请求参数 参数 必选 类型及范围 说明 client_id true string 注册 应用时分配的 ID response_type true string 返回类型 ，固定为 code redirect_uri true string 授权回调地址，需与 注册时 设置的回调地址一致 scope true string 申请 scope 权限所需参数， 只提供 read一种 state true string 用于保持请求和回调的状态，在回调时，会回传该参数。开发者可以用这
21、个参数验证请求有效性，也可以记录用户请求授权页前的位置。这个参数可用于防止跨站请求伪造（ CSRF）攻击 4) 返回数据 返回值字段 字段类型 字段说明 code string 用于调用 access_token 接口 ， 获取授权后的 access token state string 如果传递参数，会回传该参数 5) 示例 ： 请求 ： https:/mainplatform/oauth2/authorize?client_id=CLIENT_ID&redirect_uri=http:/subplatform/response&response_type=code&scope=read&state=STATE 同意授权后会重定向用户到 ： http:/subplatform/response?state=STATE&code=CODE 6. 院级 平台 获得 authorize_code,访问校级平台 的 access_token 接口 ，请求 access_token。校级平台 access_token 接口 访问标准如下： 1) URL https:/mainplatform/oauth2/access_token 2) HTTP 请求方式 POST
