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