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

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