廈門大學(xué)實(shí)驗(yàn)室資源信息管理系統(tǒng)接口說明.doc

廈門大學(xué)實(shí)驗(yàn)室資源信息管理系統(tǒng)接口說明文檔1系統(tǒng)概述廈門大學(xué)實(shí)驗(yàn)室資源信息管理系統(tǒng)，以下簡(jiǎn)稱“校級(jí)平臺(tái)”，各院級(jí)實(shí)驗(yàn)儀器管理系統(tǒng)，以下簡(jiǎn)稱“院級(jí)系統(tǒng)”。管理單位可以按照統(tǒng)一的數(shù)據(jù)標(biāo)準(zhǔn)及格式規(guī)范，通過接口的方式將報(bào)送數(shù)據(jù)至校級(jí)平臺(tái)。本接口采用REST接口方式，提交與返回的數(shù)據(jù)為JSON格式，以實(shí)現(xiàn)校級(jí)平臺(tái)與各院級(jí)系統(tǒng)在數(shù)據(jù)與服務(wù)方面的對(duì)接，更加有效地開展實(shí)驗(yàn)室資源信息管理服務(wù)。本規(guī)范適用于各院級(jí)系統(tǒng)。校級(jí)平臺(tái)與院級(jí)系統(tǒng)共涉及4個(gè)接口，具體如下：接口名稱用途預(yù)約請(qǐng)求接口接收校級(jí)平臺(tái)推送的用戶預(yù)約請(qǐng)求，返回儀器預(yù)約頁(yè)面儀器數(shù)據(jù)獲取接口接收校級(jí)平臺(tái)推送的儀器信息儀器數(shù)據(jù)報(bào)送接口接收院級(jí)系統(tǒng)向校級(jí)平臺(tái)推送儀器信息使用記錄上報(bào)接口接收院級(jí)系統(tǒng)向校級(jí)平臺(tái)推送儀器使用記錄接口用戶信息接口用于院級(jí)系統(tǒng)與校級(jí)用戶統(tǒng)一認(rèn)證和管理2接口說明2.1預(yù)約請(qǐng)求接口2.1.1接口描述：校級(jí)平臺(tái)通過該接口將預(yù)約請(qǐng)求推至院級(jí)系統(tǒng)，獲取相應(yīng)院級(jí)系統(tǒng)返回的儀器預(yù)約頁(yè)面。2.1.2請(qǐng)求消息參數(shù)描述參數(shù)名稱類型是否為空描述innerIDString否儀器所屬單位內(nèi)部的唯一編碼；insCodeString否管理單位的唯一標(biāo)識(shí)；2.1.3響應(yīng)消息參數(shù)描述參數(shù)名稱類型是否為空描述頁(yè)面的地址（url）String否儀器預(yù)約頁(yè)面的url2.1.4接口流程（1） 校級(jí)系統(tǒng)發(fā)布預(yù)約儀器服務(wù)；（2） 用戶點(diǎn)擊預(yù)約按鈕，接口將用戶的預(yù)約請(qǐng)求（儀器所屬單位內(nèi)部編碼innerID及單位唯一標(biāo)識(shí)）送至相應(yīng)的院級(jí)系統(tǒng)；（3） 院級(jí)系統(tǒng)接收到校級(jí)平臺(tái)推送的預(yù)約請(qǐng)求，通過在線平臺(tái)的預(yù)約審核流程對(duì)預(yù)約請(qǐng)求進(jìn)行審核，根據(jù)審核結(jié)果并返回具體的儀器預(yù)約頁(yè)面；（4） 用戶可以在院級(jí)系統(tǒng)返回的預(yù)約頁(yè)面中進(jìn)行儀器預(yù)約操作。2.1.5注意事項(xiàng)（1） 校級(jí)平臺(tái)統(tǒng)一分配院級(jí)單位的唯一標(biāo)識(shí)；（2） 校級(jí)平臺(tái)不提供儀器預(yù)約服務(wù)，只能將用戶預(yù)約請(qǐng)求推送至院級(jí)系統(tǒng)，由院級(jí)系統(tǒng)提供具體的儀器預(yù)約服務(wù)；（3） 院級(jí)系統(tǒng)返回給校級(jí)平臺(tái)的是具體的儀器與預(yù)約頁(yè)面url，而不是院級(jí)系統(tǒng)的首頁(yè)或其他頁(yè)面，并且確保預(yù)約頁(yè)面能打開；（4） 院級(jí)系統(tǒng)返回的預(yù)約頁(yè)面中必須包括該儀器的開放日歷及機(jī)時(shí)安排情況；2.2儀器數(shù)據(jù)獲取接口2.2.1接口描述：院級(jí)系統(tǒng)獲取校級(jí)平臺(tái)儀器數(shù)據(jù)的接口。2.2.2請(qǐng)求消息參數(shù)描述參數(shù)名稱類型是否為空描述insCodeString否院級(jí)單位的唯一標(biāo)識(shí)instruTypeint否填報(bào)數(shù)據(jù)類型：9 儀器信息2.2.3響應(yīng)消息參數(shù)描述參數(shù)名稱類型是否為空描述狀態(tài)碼int否儀器數(shù)據(jù)推送結(jié)果：100代表成功101代表數(shù)據(jù)存取成功，并根據(jù)結(jié)果提示信息200代表單位編碼錯(cuò)誤201代表填報(bào)數(shù)據(jù)類型錯(cuò)誤202代表推送的數(shù)據(jù)json字符串格式錯(cuò)誤203代表驗(yàn)證數(shù)據(jù)格式錯(cuò)誤204代表其他異常301代表數(shù)據(jù)庫(kù)操作異常儀器數(shù)據(jù)集合List否見2.2.3返回示例說明2.2.3返回示例說明status:100,list:CollegeName:xxxx,/學(xué)院名稱UnitNumber:2J02,/單位號(hào)SASACClassificationNum:2400502,/國(guó)資分類號(hào)InstrumentChineseName:xxxx,/儀器名稱(中文)InstrumentClassificationNumber:03052207,/儀器分類號(hào)Model:MCR302,/型號(hào)Specifications:MCR302,/規(guī)格UnitPrice:597916.07,/單價(jià)DateOfProduction:2013/12/6 0:00:00,/出廠日期PurchaseDate:2013/12/6 0:00:00,/購(gòu)置日期StorageTime:2014/11/25 0:00:00,/入庫(kù)時(shí)間CountryOfOrigin:xxxx,/生產(chǎn)國(guó)別CountryCode:156,/國(guó)別碼Manufacturer:xxxx/生產(chǎn)廠家2.3儀器數(shù)據(jù)報(bào)送接口2.3.1接口描述：院級(jí)系統(tǒng)上報(bào)校級(jí)平臺(tái)儀器數(shù)據(jù)的接口。2.3.2請(qǐng)求消息參數(shù)描述參數(shù)名稱類型是否為空描述insCodeString否院級(jí)單位的唯一標(biāo)識(shí)instruTypeint否填報(bào)數(shù)據(jù)類型：9 儀器信息儀器數(shù)據(jù)集合List否見儀器數(shù)據(jù)集合字段說明儀器數(shù)據(jù)集合字段說明參數(shù)名稱是否必填參數(shù)說明示例參考isCourtyardNew是是否院級(jí)新增儀器0為否 1為是CollegeName是學(xué)院名稱UnitNumber是單位號(hào)SASACClassificationNum是國(guó)資分類號(hào)InstrumentChineseName是儀器名稱（中文）InstrumentClassificationNumber是儀器分類號(hào)Model是型號(hào)Specifications是規(guī)格UnitPrice是單價(jià)DateOfProduction是出廠日期PurchaseDate是購(gòu)置日期StorageTime是入庫(kù)時(shí)間CountryOfOrigin是生產(chǎn)國(guó)別CountryCode是國(guó)別碼Manufacturer是生產(chǎn)廠家InstrumentSharingCode是儀器共享分類編碼FundsNardNumber是經(jīng)費(fèi)卡號(hào)MainTechnicalIndex是主要技術(shù)指標(biāo)MajorFundingSources是主要經(jīng)費(fèi)來源MainTestResearchArea是主要測(cè)試研究領(lǐng)域與代碼FunctionalFeatures是功能特色SharedMode是共享模式OneYearOffCampusOpen是一年內(nèi)可用于對(duì)校外開放機(jī)時(shí)MeasurementCertification是是否通過計(jì)量認(rèn)證PlacePosition是放置位置InstrumentImage是儀器圖片InstrumentResponsiblePerson是儀器負(fù)責(zé)人InstrumentResponsiblePersonTel是儀器負(fù)責(zé)人聯(lián)系電話InstrumentResponsiblePersonMail是儀器負(fù)責(zé)人電子郵箱InstrumentEinglishName否儀器名稱(英文)2.3.3響應(yīng)消息參數(shù)描述參數(shù)名稱類型是否為空描述狀態(tài)碼int否儀器數(shù)據(jù)推送結(jié)果：100代表成功101代表數(shù)據(jù)存取成功，并根據(jù)結(jié)果提示信息200代表單位編碼錯(cuò)誤201代表填報(bào)數(shù)據(jù)類型錯(cuò)誤202代表推送的數(shù)據(jù)json字符串格式錯(cuò)誤203代表驗(yàn)證數(shù)據(jù)格式錯(cuò)誤204代表其他異常301代表數(shù)據(jù)庫(kù)操作異常2.3.4接口流程（1） 校級(jí)平臺(tái)發(fā)布儀器數(shù)據(jù)報(bào)送服務(wù)；（2） 院級(jí)系統(tǒng)通過該接口推送儀器數(shù)據(jù)至校級(jí)平臺(tái)；（3） 校級(jí)平臺(tái)驗(yàn)證單位唯一標(biāo)識(shí)和儀器類別的正確性；驗(yàn)證失敗則返回相應(yīng)狀態(tài)碼；（4） 校級(jí)平臺(tái)對(duì)上報(bào)的儀器數(shù)據(jù)進(jìn)行驗(yàn)證，驗(yàn)證通過進(jìn)行數(shù)據(jù)庫(kù)存儲(chǔ)，已報(bào)過的數(shù)據(jù)則進(jìn)行更新；驗(yàn)證失敗返回相應(yīng)狀態(tài)碼；2.2.5注意事項(xiàng)（1） 院級(jí)系統(tǒng)通過接口報(bào)送的數(shù)據(jù)格式按照附錄1中儀器數(shù)據(jù)報(bào)送接口的各類型儀器示例。（2） 校級(jí)平臺(tái)統(tǒng)一分配院級(jí)單位的唯一標(biāo)識(shí)；院級(jí)單位可登錄校級(jí)平臺(tái)查看本單位的唯一標(biāo)識(shí)，院級(jí)系統(tǒng)需保存單位標(biāo)識(shí)關(guān)聯(lián)表；（3） 管理單位院級(jí)系統(tǒng)需將平臺(tái)負(fù)責(zé)人的通訊郵箱上報(bào)校級(jí)平臺(tái)；校級(jí)平臺(tái)對(duì)數(shù)據(jù)驗(yàn)證的錯(cuò)誤信息會(huì)以郵件的方式發(fā)送院級(jí)系統(tǒng)負(fù)責(zé)人的郵箱；（4） 院級(jí)系統(tǒng)接與校級(jí)平臺(tái)的對(duì)接過程中，如果多次出現(xiàn)錯(cuò)誤狀態(tài)碼，及時(shí)聯(lián)系相關(guān)人員。2.4儀器使用記錄接口2.4.1接口描述：院級(jí)系統(tǒng)將儀器使用記錄數(shù)據(jù)上報(bào)到校級(jí)平臺(tái)的接口。2.4.2請(qǐng)求消息參數(shù)描述參數(shù)名稱類型是否為空描述insCodeString否院級(jí)系統(tǒng)的唯一標(biāo)識(shí)使用記錄的集合List否詳見使用記錄的集合字段說明使用記錄的集合字段說明參數(shù)名稱是否必填參數(shù)說明示例參考AppointmentStart是預(yù)約時(shí)間（起）2013/12/6 0:00:00AppointmentEnd是預(yù)約時(shí)間（止）2013/12/6 0:00:00AppointmentLength是預(yù)約時(shí)長(zhǎng)ControllerRecordStart是控制器記錄時(shí)間（起）2013/12/6 0:00:00ControllerRecordEnd是控制器記錄時(shí)間（止）2013/12/6 0:00:00ControllerRecordLength是控制器記錄的實(shí)際測(cè)試時(shí)長(zhǎng)SampleNumber否樣品個(gè)數(shù)SendSampleName是預(yù)約或送樣人姓名SendSampleNumber是預(yù)約或送樣人教工號(hào)（學(xué)工號(hào)）SendSampleGroup是預(yù)約或送樣人所屬課題組SendSampleGroupHead是預(yù)約或送樣人所屬課題組負(fù)責(zé)人CardPersonName是刷卡人姓名CardPersonNumber是刷卡人教工號(hào)（學(xué)工號(hào)）CardPersonGroup是刷卡人所屬課題組OrderItemName否預(yù)約檢測(cè)項(xiàng)目名稱SendSampleItemName否送樣檢測(cè)項(xiàng)目名稱2.4.3響應(yīng)消息參數(shù)描述參數(shù)名稱類型是否為空描述狀態(tài)碼int否服務(wù)成效數(shù)據(jù)推送結(jié)果：100代表成功200代表單位編碼錯(cuò)誤201代表推送的數(shù)據(jù)json字符串格式錯(cuò)誤202代表數(shù)據(jù)驗(yàn)證錯(cuò)誤203代表其他異常301代表數(shù)據(jù)庫(kù)操作異常2.4.4接口流程（1） 校級(jí)貴重儀器設(shè)備管理系統(tǒng)根據(jù)從各學(xué)院抓取的儀器設(shè)備使用情況數(shù)據(jù)作為計(jì)費(fèi)數(shù)量的依據(jù)；（2） 院級(jí)系統(tǒng)調(diào)用該接口將單位的儀器設(shè)備使用情況數(shù)據(jù)推送至校級(jí)平臺(tái)；（3） 校級(jí)平臺(tái)首先驗(yàn)證單位唯一標(biāo)識(shí)的正確性，驗(yàn)證通過則獲取儀器設(shè)備使用情況數(shù)據(jù)；驗(yàn)證失敗則返回相應(yīng)的狀態(tài)碼；（4） 校級(jí)平臺(tái)將上報(bào)的儀器設(shè)備使用情況數(shù)據(jù)進(jìn)行驗(yàn)證，驗(yàn)證通過則保存到數(shù)據(jù)庫(kù)中，驗(yàn)證失敗則返回相應(yīng)的狀態(tài)碼；2.3.5注意事項(xiàng)（1） 院級(jí)系統(tǒng)通過該接口報(bào)送的儀器設(shè)備使用情況數(shù)據(jù)按照附錄1中的儀器使用記錄接口的示例。（2） 校級(jí)平臺(tái)統(tǒng)一分配院級(jí)單位的唯一標(biāo)識(shí)；院級(jí)系統(tǒng)需保存單位標(biāo)識(shí)關(guān)聯(lián)表；院級(jí)單位可登錄校級(jí)平臺(tái)查看本單位的唯一標(biāo)識(shí)；（3） 院級(jí)系統(tǒng)需將平臺(tái)負(fù)責(zé)人的通訊郵箱地址上報(bào)校級(jí)平臺(tái)；校級(jí)平臺(tái)對(duì)數(shù)據(jù)的驗(yàn)證錯(cuò)誤信息會(huì)以郵件的方式發(fā)送院級(jí)系統(tǒng)負(fù)責(zé)人的郵箱；（4） 院級(jí)系統(tǒng)接與校級(jí)平臺(tái)的對(duì)接過程中，如果多次出現(xiàn)錯(cuò)誤的狀態(tài)碼，需聯(lián)系相關(guān)人員。2.5用戶信息接口校級(jí)平臺(tái)提供用戶信息接口，用于院級(jí)系統(tǒng)與校級(jí)平臺(tái)的用戶統(tǒng)一認(rèn)證和管理。具體詳情見Oauth說明文檔。對(duì)接用戶認(rèn)證開發(fā)指南一、 Oauth2.0授權(quán)訪問流程（1） 管理單位網(wǎng)站重定向用戶到校級(jí)平臺(tái)提供的authorize接口，如果用戶同意授權(quán)，校級(jí)平臺(tái)會(huì)把用戶重定向回到院級(jí)單位網(wǎng)站，并附上授權(quán)碼authorize_code；（2） 校級(jí)單位網(wǎng)站使用authorize_code向校級(jí)平臺(tái)的access_token接口發(fā)起請(qǐng)求，校級(jí)平臺(tái)在驗(yàn)證請(qǐng)求合法后，會(huì)返回訪問令牌access_token；（3） 校級(jí)單位網(wǎng)站使用access_token向resource接口發(fā)起請(qǐng)求，獲取用戶信息。二、 單位平臺(tái)工作流程1. 用戶在校級(jí)平臺(tái)發(fā)起“預(yù)約儀器”請(qǐng)求，校級(jí)平臺(tái)將請(qǐng)求重定向到院級(jí)平臺(tái)。2. 院級(jí)平臺(tái)檢查用戶登錄狀態(tài)，若是登錄狀態(tài)，則直接轉(zhuǎn)到儀器預(yù)約頁(yè)面；若處于未登錄狀態(tài)，則轉(zhuǎn)到步驟3代表的登錄頁(yè)面。3. 單位平臺(tái)的登錄頁(yè)面中要有“使用校級(jí)平臺(tái)賬號(hào)登錄”入口。4. 若用戶選擇直接使用院級(jí)平臺(tái)賬號(hào)登錄，則登陸后轉(zhuǎn)到儀器預(yù)約頁(yè)面；若用戶選擇“使用校級(jí)平臺(tái)賬號(hào)登錄”，則開始o(jì)auth2.0授權(quán)認(rèn)證過程。5. 重定向用戶到校級(jí)平臺(tái)authorize接口，請(qǐng)求authorize_code。校級(jí)平臺(tái)authorize接口訪問標(biāo)準(zhǔn)如下：1) URLhttps:/mainplatform/oauth2/authorize2) HTTP請(qǐng)求方式GET/POST3) 請(qǐng)求參數(shù)參數(shù)必選類型及范圍說明client_idtruestring注冊(cè)應(yīng)用時(shí)分配的IDresponse_typetruestring返回類型，固定為coderedirect_uritruestring授權(quán)回調(diào)地址，需與注冊(cè)時(shí)設(shè)置的回調(diào)地址一致scopetruestring申請(qǐng)scope權(quán)限所需參數(shù)，只提供read一種statetruestring用于保持請(qǐng)求和回調(diào)的狀態(tài)，在回調(diào)時(shí)，會(huì)回傳該參數(shù)。開發(fā)者可以用這個(gè)參數(shù)驗(yàn)證請(qǐng)求有效性，也可以記錄用戶請(qǐng)求授權(quán)頁(yè)前的位置。這個(gè)參數(shù)可用于防止跨站請(qǐng)求偽造（CSRF）攻擊4) 返回?cái)?shù)據(jù)返回值字段字段類型字段說明codestring用于調(diào)用access_token接口，獲取授權(quán)后的access tokenstatestring如果傳遞參數(shù)，會(huì)回傳該參數(shù)5) 示例：請(qǐng)求：https:/mainplatform/oauth2/authorize?client_id=CLIENT_ID&redirect_uri=http:/subplatform/response&response_type=code&scope=read&state=STATE同意授權(quán)后會(huì)重定向用戶到：http:/subplatform/response?state=STATE&code=CODE6. 院級(jí)平臺(tái)獲得authorize_code,訪問校級(jí)平臺(tái)的access_token接口，請(qǐng)求access_token。校級(jí)平臺(tái)access_token接口訪問標(biāo)準(zhǔn)如下：1) URLhttps:/mainplatform/oauth2/access_token2) HTTP請(qǐng)求方式POST3) 請(qǐng)求參數(shù)參數(shù)必選類型及范圍說明client_idtruestring注冊(cè)應(yīng)用時(shí)分配的IDclient_secrettruestring注冊(cè)應(yīng)用時(shí)分配的secretgrant_typetruestring請(qǐng)求的類型，填寫authorization_codecodetruestring調(diào)用authorize獲得的code值redirect_uritruestring回調(diào)地址，需與注冊(cè)應(yīng)用里的回調(diào)地址一致4) 返回?cái)?shù)據(jù)返回值字段字段類型字段說明access_tokenstring用于調(diào)用資源訪問接口，獲取用戶數(shù)據(jù)expires_instringaccess_token的生命周期，單位是秒數(shù)5) 示例請(qǐng)求：https:/mainplatform/oauth2/access_token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=CODE&redirect_uri=http:/subplatform/response成功獲取后返回?cái)?shù)據(jù)： access_token: ACCESS_TOKEN, expires_in: 1234,7. 獲得校級(jí)平臺(tái)返回的access_token,訪問校級(jí)平臺(tái)resource接口