厦门大学实验室资源信息管理系统接口说明文档

厦门大学试验室资源信息管理系统

接口阐明文档

1系统概述

厦门大学试验室资源信息管理系统，如下简称“校级平台”，各院级试验仪

器管理系统，如下简称“院级系统”。管理单位可以按照统一的I数据原则及格式

规范，通过接口的方式将报送数据至校级平台。

本接口采用REST接口方式，提交与返回的数据为JSON格式，以实现校级平

台与各院级系统在数据与服务方面的对接，愈加有效地开展试验室资源信息管理

服务。

本规范合用于各院级系统。

校级平台与院级系统共波及4个接口，详细如下:

接口名称用途

预约祈求接口接受校级平台推送的顾客预约祈求，返回仪器预约页面

仪器数据获取接口接受校级平台推送的仪器信息

仪器数据报送接1」接受院级系统向校级平台推送仪器信息

使用记录上报接口接受院级系统向校级平台推送仪器使用记录接口

顾客信息接口用于院级系统与校级顾客统一认证和管理

2接口阐明

2・1预约祈求接口

2.1.1接口描述：校级平台通过该接口将预约祈求推至院级系统，获取对应院级

系统返回的仪器预约页面。

2.1.2祈求消息参数描述

参数名称类型与否为空描述

innerlDString否仪器所属单位内部的唯一编码；

insCodeString否管理单位的唯一标识；

2.1.3响应消息参数描述

参数名称类型与否为空描述

页面的地址（url）String否仪器预约页面的url

2.1.4接口流程

（1）校级系统公布.预约仪器服务；

（2）顾客点击预约按钮，接口将顾客日勺预约祈求（仪器所属单位内部编码

innerlD及单位唯一标识）送至对应的院级系统；

（3）院级系统接受到校级平台推送的预约祈求，通过在线平台的预约审核

流程对预约祈求进行审核，根据审核成果并返回详细日勺仪器预约页面；

（4）顾客可以在院级系统返回的预约页面中进行仪器预约操作。

2.1.5注意事项

（1）校级平台统一分派院级单位日勺唯一标识；

（2）校级平台不提供仪器预约服务，只能将颐客预约祈求推送至院级系统,

由院级系统提供详细H勺仪器预约服务；

（3）院级系统返回给校级平台的是详细的I仪器与预约页面url,而不是院级

系统的首页或其他页面，并且保证预约页而能打开；

（4）院级系统返回日勺预约页面中必须包括该仪器日勺开放F1历及机时安排状

况；

2.2仪器数据获取接口

221接口描述：院级系统获取校级平台仪器数据的接口°

2.2.2祈求消息参数描述

参数名称类型与否为空描述

insCodeString否院级单位日勺唯一标识

instruTypeint否填报数据类型：

9仪器信息

2.2.3响应消息参数描述

参数名称类型与否为空描述

状态码int否仪器数据推送成果：

100代表成功

101代表数据存取成功，并根据成果提

醒信息

200代表单位编码错误

201代表填报数据类型错误

202代表推送的数据json字符串格式

错误

203代表验证数据格式错误

204代表其他异常

301代表数据库操作异常

仪器数据集合List<String>否见223返回示例阐明

223返回示例阐明

{"statusMOO,

“CollegeName":”xxxx”,〃学院名称

，1讪1^^”902，〃单位号

“SASACCIassificationNum”:“2400502”,〃国资分类号

“InstrumentChineseNameYxxxx”,〃仪器名称（中文）

“InstrumentClassificationNumbe严:"03052207”,〃仪器分类号

“Model”:“MCR302，〃型号

“Specifications":“MCR302”,〃规格

“UnitPrice”:“597916.07”,〃单价

"DateOfProduction":"2023\/12\^0:00:00”,〃出厂日期

"PurchaseDate":"2023\/12\?60:00:00"〃购置口期

“StorageTime”:“2023Vll\Z250:00:00，〃入库时间

-011而701。日酬丫取乂乂”,〃生产国别

"011田「丫（20£|即:叮56,,,〃国另11码

“Manufacturer”:“xxxx”〃生产厂家

}

]

）

2.3仪器数据报送接口

2.3.1接口描述：院级系统上报校级平台仪器数据的接口。

2.3.2祈求消息参数描述

参数名称类型与否为空描述

insCodeString否院级单位的唯一标识

instruTypeint否填报数据类型：

9仪器信息

仪器数据集合List<String>否见仪器数据集合字段阐明

仪器数据集合字段阐明

参数名称与否必填参数阐明示例参照

isCourtyardNew与否院级新增仪器。为否1为是

是

学院名称

CollegeName是

单位号

UnitNumber是

SASACCIassificationNum国资分类号

是

InstrumentChineseName仪器名称（中文）

是

InstrumentClassificationNumber仪器分类号

是

型号

Model是

规格

Specifications是

单价

UnitPrice是

出厂日期

DateOfProduction是

购置日期

PurchaseDate是

StorageTime入库时间

是

CountryOfOrigin生产国别

是

CountryCode国别码

是

Manufacturer生产厂家

是

InstrumentSharingCode仪器共享分类编码

是

FundsNardNumber经费卡号

是

MainTechnicallndex重要技术指标

是

重要经费来源

MajorFundingSources是

MainTestResearchArea重要测试研究领域与代码

是

FunctionalFeatures功能特色

是

SharedMode共享模式

是

OneYearOffCampusOpen一年内可用于对校外开放

是

机时

Measurementcertification与否通过计量认证

是

Placeposition放置位置

是

Instrumentimage仪器图片

是

仪器负责人

InstrumentResponsiblePerson是

仪器负责人联络

InstrumentResponsiblePersonTel是

InstrumentResponsiblePersonMail仪器负责人电子邮箱

是

InstrumentEinglishName仪器名称（英文）

否

2.3.3响应消息参数描述

参数名称类型与否为空描述

状态码int否仪器数据推送成果：

100代表成功

101代表数据存取成功，并根据成果提

醒信息

200代表单位编码错误

201代表填报数据类型错误

202代表推送口勺数据json字符串格式

错误

203代表验证数据格式错误

204代表其他异常

301代表数据库操作异常

2.3.4接口部次呈

（1）校级平台公布仪器数据报送服务；

（2）院级系统通过该接口推送仪潜数据至校级平台；

（3）校级平台验证单位唯一标识和仪器类别时对日勺性；验证失败则返回对

应状态码;

（4）校级平台对上报日勺仪器数据进行验证，验证通过进行数据库存储，已

报过时数据则进行更新；验证失败返回对应状态码；

2.2.5注意事项

（1）院级系统通过接口报送日勺数据格式按照附录1中仪器数据报送接口的

各类型仪器示例。

（2）校级平台统一分派院级单位欧I唯一标识；院级单位可登录校级平台查

看本单位的唯一标识，院级系统需保留单位标识关联表；

（3）管理单位院级系统需将平台负责人日勺通讯邮箱上报校级平台；校级平

台对数据验证的I错误信息会以邮件的方式发送院级系统负责人的邮箱；

（4）院级系统接与校级平台日勺对接过程中，假如多次出现错误状态码,及

时联络有关人员。

2.4仪器使用记录接口

241接口描述：院级系统将仪器使用记录数据上报到校级平台日勺接口。

242祈求消息参数描述

参数名称类型与否为空描述

insCodeString否院级系统的唯一标识

使用记录的集合List<String>否详见使用记录H勺集合字段阐明

使用记录的集合字段阐明

参数名称与否必填参数阐明示例参照

Appointmentstart预约时间（起）202歹1%0:00:00

是

AppointmentEnd预约时间（止）

是202^1^60:00:00

AppointmentLength预约时长

是

ControllerRecordSta控制器记录时间（起）202)1如0:00:00

是

rt

ControllerRecordEn控制器记录时间（止）202羽如0:00:00

是

d

CnntrnllprRpcnrdlp控制器记录的实际测试时长

是

ngth

SampleNumber样品个数

否

SendSampleName预约或送样人姓名

是

SendSampleNumbe预约或送样人教工号（学工号）

是

r

SendSampleGroup预约或送样人所属课题组

是

SendSampleGroupH预约或送样人所属课题组负责

是

ead人

CardPersonName刷卡人姓名

是

CardPersonNumber刷卡人教工号（学工号）

是

CardPersonGroup刷卡人所属课题组

是

OrderltemName预约检测项目名称

否

SendSampleltemNa送样检测项目名称

否

me

2.4.3响应消息参数描述

参数名称类型与否为空描述

服务成效数据推送成果：

状态码int否

100代表成功

200代表单位编码错误

201代表推送的数据json字符串格式

错误

202代表数据验证错误

203代表其他异常

301代表数据库操作异常

2.4.4接口流程

（1）校级珍贵仪器设备管理系统根据从各学院抓取欧I仪器设备使用状况数

据作为计费数量日勺根据；

（2）院级系统调用该接口将单位日勺仪器设备使用状况数据推送至校级平

台；

（3）校级平台首先验证单位唯一标识日勺对的性，验证通过则获取仪潜设备

使用状况数据；验证失败则返回对应日勺状态码；

（4）校级平台将上报的仪器设备使用状况数据进行验证，验证通过则保留

到数据库中，验证失败则返回对应的状态码；

2.3.5注意事项

（1）院级系统通过该接口报送的仪器设备使用状况数据按照附录1中日勺仪

港使用记录接口日勺示例。

（2）校级平台统一分派院级单位的唯一标识；院级系统需保留单位标识关

联表：院级单位可登录校级平台杳看本单位的J唯一标识：

（3）院级系统需将平台负责人日勺通讯邮箱地址上报校级平台；校级平台对

数据的验证错误信息会以邮件的方式发送院级系统负责人的邮箱；

（4）院级系统接与校级平台的对接过程中，假如多次出现错误的状态码，

需联络有关人员。

2.5顾客信息接口

校级平台提供顾客信息接口，用于院级系统与校级平台的顾客统一认证和管

理。详细详情见Oauth阐明文档。

对接顾客认证开发指南

一、Oauth2.0授权访问流程

（1）管理单位网站重定向顾客到校级平台提供口勺authorize接口，假如顾客同意授权,

校级平台会把顾客重定向回到院级单位网站，并附上授权码authorize_code；

（2）校级单位网站使用authorize_code向校级平台的access_token接口发起祈求，校

级平台在验证祈求合法后，会返回访问令牌access_token；

(3)校级单位网站使用access_token向resource接口发起祈求，获取顾客信息。

二、单位平台工作流程

1.顾客在校级平台发起“预约仪器”祈求，校级平台将祈求重定向到院级平台。

2.院级平台检查顾客登录状态，若是登录状态，则直接转到仪器预约页面；若处在未登录

状态，则转到环节3代表"勺登录页面。

3.单位平台口勺登录页面中要有“使用校级平台账号登录”入口。

4.若顾客选择直接使用院级平台账号登录，则登陆后转到仪器预约页面.：若顾客选择“使

用校级平台账号登录"，则开始oauth2.0授权认证过程。

5.重定向顾客到校级平台authorize接口，祈求authorize_codeo校级平台authorize接口访

问原则如下：

1)URL

s://mainplatform/oauth2/authorize

2)祈求方式

GET/POST

3)祈求参数

参数必选类型及范围阐明

clientjdtruestring注册应用时分派的ID

response_typetruestring返回类型，固定为code

redirect_uritruestring授权Pl调地址，需与注册时设置的问

调地址一致

scopetruestring申请scope权限所需参数，只提供read

一种

statetruestring用于保持祈求和回调的状态，在回调

时，会回传该参数。开发者可以用这

个参数验证祈求有效性，也可以记录

顾客祈求授权页前的位置。这个参数

可用于防止跨站祈求伪造（CSRF）袭

击

4）返回数据

返回值字段字段类型字段阐明

codestring用丁调用accebi»_loken接

口，获取授权后於Jaccess

token

statestring假如传递参数，会回传该参

数

5）示例:

祈求:

s://mainplatform/oauth^authorize?client_id=CUENT_ID&redirect_uri=://subplatform/

response&response_type=code&scope=read&state=STATE

同意授权后会重定向顾客到：

://subplatform/response?state=STATE&code=CODE

6.院级平:台获得authorize_code,访问校级平台的access_token接口，祈求access_token（,校

级平台access_token接口访问原则如下：

1）URL

s://mainplatform/oauth^/access_token

2）祈求方式

POST

3）祈求参数

参数必选类型及范围阐明

clientjdtruestring注册应用时分派口勺ID

client_secrettruestring注册应用时分派日勺secret

grant_typetruestring祈求的J类型，填写authorization_code

codetruestring调用authorize获得日勺code值

redirect_uritruestring回调地址，需与注册应用里的回调地址

一致

4）返回数据

返回值字段字段类型字段阐明

access_tokenstring用于调用资源访问接口，获

取顾客数据

expires_instringacces