局域網(wǎng)考試系統(tǒng)接口文檔¶
單點(diǎn)登錄¶
注:
1.接口地址的host部分請(qǐng)?zhí)鎿Q成您部署的ip+端口或者域名再使用。
2.code(權(quán)限碼)在優(yōu)考試系統(tǒng)的系統(tǒng)設(shè)置->開放平臺(tái)設(shè)置處獲取。
單點(diǎn)登錄允許考生只在用戶的系統(tǒng)上登錄一次,點(diǎn)擊試卷考試時(shí)不再需要再次登錄, 例如用戶A有公司自己的OA系統(tǒng), 考生王二登錄到公司的OA系統(tǒng)后, 在系統(tǒng)里點(diǎn)開始考試,這時(shí)王二就不再需要輸入自己的賬號(hào),而是直接就進(jìn)入考試了。
1、單點(diǎn)登錄考試¶
單點(diǎn)登錄考試允許用戶考生直接在用戶系統(tǒng)上點(diǎn)擊就開始考試, 不再需要額外的身份認(rèn)證, 接口如下:
請(qǐng)求
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.newStudentSSO&format=raw
請(qǐng)求數(shù)據(jù)
code=權(quán)限碼&loginValue=登錄字段的值&password=密碼&eid=試卷ID
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- loginValue 表示的是考生的登錄值,比如說系統(tǒng)設(shè)置了使用手機(jī)登錄,那么這里就是考生的手機(jī)號(hào)碼。
- password 考生的密碼,如果有的話;如果考生沒有的話,這里留空
- eid 考生要做的試卷ID
登錄成功后,系統(tǒng)會(huì)自動(dòng)跳轉(zhuǎn)到考試界面,且不需要再執(zhí)行身份驗(yàn)證
2、單點(diǎn)登錄考生后臺(tái)¶
單點(diǎn)登錄到考生后臺(tái)和單點(diǎn)登錄考試原理一樣, 差別是不傳eid參數(shù)或傳0. 即:
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.newStudentSSO&format=raw&loginValue=13487361736&password=1294783&eid=0
系統(tǒng)判斷eid為0時(shí)會(huì)自動(dòng)跳轉(zhuǎn)到考生后臺(tái)界面
3、子管理員單點(diǎn)登錄¶
子管理員單點(diǎn)登錄管理后臺(tái), 接口如下:
請(qǐng)求
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.childAdminSSO&format=raw
請(qǐng)求數(shù)據(jù)
code=權(quán)限碼&email=郵箱&password=密碼
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- email 子管理員郵箱,必填
- password 子管理員密碼,必填
登錄成功后,系統(tǒng)會(huì)自動(dòng)跳轉(zhuǎn)到管理后臺(tái)
獲取考生成績¶
注:
1.接口地址的host部分請(qǐng)?zhí)鎿Q成您部署的ip+端口或者域名再使用。
2.code(權(quán)限碼)在優(yōu)考試系統(tǒng)的系統(tǒng)設(shè)置->開放平臺(tái)設(shè)置處獲取。
1、獲取某一考生參與考試的記錄¶
通過該接口,可以獲取考生在某一份試卷下的考生成績。
接口如下所示:
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.queryResults&format=raw
參數(shù):
code=權(quán)限碼&eid=試卷ID&loginValues=考生登錄字段值&start=0&limit=30
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- eid 表示試卷ID
- loginValues 表示的是考生的登錄值,可選參數(shù),比如說系統(tǒng)設(shè)置了使用手機(jī)登錄,那么這里就是考生的手機(jī)號(hào)碼
- year 用于查詢不同年份的數(shù)據(jù),默認(rèn)為當(dāng)前年份 例:2022,可選參數(shù)
- start 用于數(shù)據(jù)量很大時(shí)的分頁顯示,表示分頁的數(shù)據(jù)偏移, 默認(rèn)為0, 可選參數(shù)
- limit 用于數(shù)據(jù)量很大時(shí)的分布顯示,設(shè)置每頁的數(shù)據(jù)顯示數(shù)量,默認(rèn)為30, 可選參數(shù)
該接口返回考生在這個(gè)試卷里的所有考試記錄信息
[
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//查看詳細(xì)考試詳情的鏈接,有30分鐘時(shí)間限制,超過30分鐘后得重新獲取鏈接
"score": 30,//考試得分,float類型
"startTime": 1539075728,//考生開始作答的時(shí)間戳,int類型,單位s(秒)
"endTime": 1539075828,//考生交卷的時(shí)間戳,int類型,單位s(秒)
"status": 1,//status 表示答卷狀態(tài),1表示正常交卷, 0正在考試中,2表示超時(shí)自動(dòng)交卷,3表示被管理員強(qiáng)制交卷,4表示系統(tǒng)執(zhí)行交卷
},
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//查看詳細(xì)考試詳情的鏈接,有30分鐘時(shí)間限制,超過30分鐘后得重新獲取鏈接
"score": 32,//考試得分,float類型
"startTime": 1539075628,//考生開始作答的時(shí)間戳,int類型,單位s(秒)
"endTime": 1539075828,//考生交卷的時(shí)間戳,int類型,單位s(秒)
"status": 1,//status 表示答卷狀態(tài),1表示正常交卷, 0正在考試中,2表示超時(shí)自動(dòng)交卷,3表示被管理員強(qiáng)制交卷,4表示系統(tǒng)執(zhí)行交卷
},
]
2、獲取參與考試的所有考試記錄信息¶
如果沒有指定 loginValues 的話, 則返回的是所有參與該試卷考試的考試記錄數(shù)據(jù)
[
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//查看詳細(xì)考試詳情的鏈接,有30分鐘時(shí)間限制,超過30分鐘后得重新獲取鏈接
"score": 30,//考試得分,float類型
"startTime": 1539075728,//考生開始作答的時(shí)間戳,int類型,單位s(秒)
"endTime": 1539075828,//考生交卷的時(shí)間戳,int類型,單位s(秒)
"loginValues": 19382,
"name": "王二"
},
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//查看詳細(xì)考試詳情的鏈接,有30分鐘時(shí)間限制,超過30分鐘后得重新獲取鏈接
"score": 32,//考試得分,float類型
"startTime": 1539075628,//考生開始作答的時(shí)間戳,int類型,單位s(秒)
"endTime": 1539075828,//考生交卷的時(shí)間戳,int類型,單位s(秒)
"loginValues": 19310, //考生登錄字段值
"name": "張三" //考生的姓名
},
]
3、獲取試卷列表¶
試卷很多的情況下需要通過接口來動(dòng)態(tài)獲取試卷列表。接口如下:
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.getExams&format=raw
參數(shù)
code=權(quán)限碼&start=0&limit=30
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- start 用于數(shù)據(jù)量很大時(shí)的分頁顯示,表示分頁的數(shù)據(jù)偏移, 默認(rèn)為0, 可選參數(shù)
- limit 用于數(shù)據(jù)量很大時(shí)的分布顯示,設(shè)置每頁的數(shù)據(jù)顯示數(shù)量,默認(rèn)為30, 可選參數(shù)
返回?cái)?shù)據(jù):
[
{
"eid": 23812,//試卷id,int類型
"title": "測(cè)試試卷", // 試卷標(biāo)題,string類型
"img": "http://192.168.0.1:5858/xxxxx.jpg",// 試卷封面圖片鏈接,string類型
"url": "http://192.168.0.1:5858/23812", //試卷考試鏈接,string類型
"createTime": 1539075828,//試卷創(chuàng)建時(shí)間的unix時(shí)間戳,int類型,單位s(秒)
"available": 1, //試卷是否可用,int類型,1表示可用,0表示不可用
"times": 3918, //試卷的考試次數(shù)
"category": "模考" //試卷的分類名稱
},
...
]
考生數(shù)據(jù)管理¶
注:
1.接口地址的host部分請(qǐng)?zhí)鎿Q成您部署的ip+端口或者域名再使用。
2.code(權(quán)限碼)在優(yōu)考試系統(tǒng)的系統(tǒng)設(shè)置->開放平臺(tái)設(shè)置處獲取。
1、獲取考生字段信息¶
獲取考生字段信息, 接口如下:
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.getStudentFields&format=raw
code=權(quán)限碼
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
返回?cái)?shù)據(jù):
[
{
"sFid":1,// 字段id,int類型
"label": "姓名", //字段標(biāo)題, string類型
"isLoginField": false, //是否為登錄字段,只能存在一個(gè)登錄字段,不存在或等于false為普通字段,boolean類型
}
]
正常返回的數(shù)據(jù)如下:
[
{
"sFid": 1,
"sLabel": "姓名"
},
{
"sFid": 2,
"sLabel": "性別"
},
{
"sFid": 4,
"sLabel": "手機(jī)"
},
{
"sFid": 5,
"sLabel": "身份證"
},
{
"sFid": 10,
"sLabel": "密碼"
},
//以上字段為系統(tǒng)默認(rèn)字段,實(shí)際可能存在更多字段,請(qǐng)以實(shí)際獲取的對(duì)象為準(zhǔn)
...
]
字段的添加和修改請(qǐng)到系統(tǒng)的考生管理中處理
2、批量插入考生信息¶
通過該接口,可以添加一個(gè)或多個(gè)考生。
接口如下所示:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.addStudentsV2&format=raw
參數(shù):
code=權(quán)限碼
students=[ //考生數(shù)組,每個(gè)元素對(duì)象代表一個(gè)考生
{ //代表一個(gè)考生信息對(duì)象
"gid": 11, //考生所屬組的id
"fields": [ //考生信息
{
"sFid": 1, // 考生字段id,int類型,該值可通過"獲取考生信息字段"API獲取,如"手機(jī)"字段id為4, 姓名字段為1
"value":"王二" //考生字段的值,如sFid的值為1,這里則填寫姓名
},
...
{
"sFid": 4, // 考生字段id,int類型,該值可通過"獲取考生信息字段"API獲取,如"手機(jī)"字段id為4, 姓名字段為1
"value":"13800000000" //考生字段的值,如sFid的值為4,這里則填寫手機(jī)號(hào)碼
}
]
},
...
{ //代表一個(gè)考生信息對(duì)象
"gid": 11, //考生所屬組的id
"fields": [ //考生信息
{
"sFid": 1, // 考生字段id,int類型,該值可通過"獲取考生信息字段"API獲取,如"手機(jī)"字段id為4, 姓名字段為1
"value":"張三" //考生字段的值,如sFid的值為1,這里則填寫姓名
},
...
{
"sFid": 4, // 考生字段id,int類型,該值可通過"獲取考生信息字段"API獲取,如"手機(jī)"字段id為4, 姓名字段為1
"value":"13800000001" //考生字段的值,如sFid的值為4,這里則填寫手機(jī)號(hào)碼
}
]
}
]
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- students 表示要添加的考生信息, 其中g(shù)id表示這個(gè)考生要加入到哪個(gè)組,如果是多個(gè)組,請(qǐng)用逗號(hào)分隔的字符串表示。 fields表示考生的信息項(xiàng)。
該接口返回成功添加的考生sid
{
"status": "ok", //成功返回 ok,失敗返回 error
"success": [ //成功添加的數(shù)據(jù),每個(gè)元素都是對(duì)象,sid表示考生id, index表示要添加考生的數(shù)據(jù)索引
{
"sid":123,
"index":1
},
{
"sid":125,
"index":2
}
],
"fail": [3,4,5] //fail表示失敗的考生索引
}
3、批量修改考生信息¶
通過該接口,可以修改一個(gè)或多個(gè)考生的信息 接口如下所示:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.updateStudents&format=raw
參數(shù):
code=權(quán)限碼
stuInfo=[ //考生數(shù)組,每個(gè)元素對(duì)象代表一個(gè)考生
{ //代表一個(gè)考生信息對(duì)象
"sid": 11, //考生id,id和登錄值不能同時(shí)為空,必須填寫一個(gè)
"loginValue":"小明" //考生登錄值,id和登錄值不能同時(shí)為空,必須填寫一個(gè)
"fields": [ //考生信息
{
"sFid": 1, // 考生字段id,int類型,該值可通過"獲取考生信息字段"API獲取,如"手機(jī)"字段id為4, 姓名字段為1
"value":"王二" //考生字段的值,如sFid的值為1,這里則填寫姓名
},
]
},
]
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- stuInfo 表示要更新的考生信息, sid表示考生ID, loginValue表示考生登錄值, fields表示考生的字段信息
該接口返回成功修改的考生sid或登錄值
{
"status": "ok", //成功返回 ok,失敗返回 error
"success": [1,2], //表示成功的考生id或登錄值
"fail": [3,4,5] //fail表示失敗的考生id或登錄值
}
4、批量刪除考生信息¶
使用該接口刪除一個(gè)或多個(gè)考生。 接口如下所示:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.delStudents&format=raw
參數(shù):
code=權(quán)限碼
loginValues=["1000","10001"] //考生登錄值列表,字符串?dāng)?shù)組,id和登錄值二選一,優(yōu)先讀取登錄值
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- loginValues 表示要?jiǎng)h除的考生登錄值列表
該接口返回成功刪除的考生sid或登錄值
{
"status": "ok", //成功返回 ok,失敗返回 error
"success": [1,2], //表示成功的考生sid或登錄值
"fail": [3,4,5] //fail表示失敗的考生的sid或登錄值
}
失敗則返回:
{
"status": "error", //成功返回 ok,失敗返回 error
"error": "無效的sid" //error為失敗的錯(cuò)誤信息
}
5、移動(dòng)考生到組¶
使用該接口移動(dòng)一個(gè)或多個(gè)考生到一個(gè)或多個(gè)組。 接口如下所示:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.mvStudents&format=raw
參數(shù):
code=權(quán)限碼
mvStuInfo={
"gids": [22,33], //如果gids里有多個(gè)值,則表示把考生添加到這些組(PS 一個(gè)考生允許同時(shí)存在多個(gè)組)
"loginValues":["小明","小紅"] //考生登錄字段值,字符串?dāng)?shù)組
"action": "addto|moveto" //操作, addto表示添加到組,這個(gè)時(shí)候一個(gè)考生可能存在多個(gè)組, moveto表示移動(dòng)到組,這個(gè)時(shí)候考生只存在一個(gè)組。如果action值為moveto,則gids只能為一個(gè),如果有多個(gè)gid, 只取第一個(gè)
}
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- mvStuInfo 表示要移動(dòng)的數(shù)據(jù)信息
該接口返回成功添加的考生loginValue
{
"status": "ok", //成功返回 ok,失敗返回 error
"success": [1,2], //表示成功的考生登錄字段值
"fail": [3,4,5] //fail表示失敗的考生登錄字段值
}
失敗則返回:
{
"status": "error", //成功返回 ok,失敗返回 error
"error": "無效的sid" //error為失敗的錯(cuò)誤信息
}
6、獲取考生信息¶
使用該接口獲取一個(gè)或多個(gè)考生的信息 接口如下所示:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.getStudentsInfo&format=raw
參數(shù):
code=權(quán)限碼
loginValues=[13212,2382,392]
參數(shù)說明:
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- loginValues 表示考生登錄字段值列表
一次最多只能查10個(gè)考生的信息
該接口成功則返回
{
"status": "ok", //成功返回 ok,失敗返回 error
"data": [
{
"loginValue":"王二",//考生登錄值,若請(qǐng)求的是loginValues,則返回loginValue
"fields":[
{
"sFid":1,
"label":"姓名",
"value": "王二"
},
{
"sFid":13,
"label":"單位",
"value": "全部門"
}
],
"group": [
"gid": 123, //組的ID
"title": "英文學(xué)習(xí)小組" //組名稱
]
},
{
"loginValue": 3925, //考生的ID
"loginValue":"張三",//考生登錄值,若請(qǐng)求的是loginValues,則返回loginValue
"fields":[
{
"sFid":1,
"label":"姓名",
"value": "張三"
},
{
"sFid":13,
"label":"單位",
"value": "全部門"
}
],
"group": [
"gid": 123, //組的ID
"title": "英文學(xué)習(xí)小組" //組名稱
]
}
]
}
失敗則返回:
{
"status": "error", //成功返回 ok,失敗返回 error
"error": "無效的sid" //error為失敗的錯(cuò)誤信息
}
如有問題,請(qǐng)隨時(shí)聯(lián)系我們客服
同步組織結(jié)構(gòu)¶
注:
1.接口地址的host部分請(qǐng)?zhí)鎿Q成您部署的ip+端口或者域名再使用。
2.code(權(quán)限碼)在優(yōu)考試系統(tǒng)的系統(tǒng)設(shè)置->開放平臺(tái)設(shè)置處獲取。
同步考生數(shù)據(jù)可以方便的在系統(tǒng)之間進(jìn)行考生數(shù)據(jù)交換,避免手動(dòng)可能出現(xiàn)的錯(cuò)誤;自動(dòng)同步及時(shí)快捷,即可以同步考生信息也可以同步考生的組織結(jié)構(gòu)。
1、新增分組¶
添加考生分組的接口如下:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.newGroup&format=raw
參數(shù):
code=權(quán)限碼&title=組標(biāo)題&parentGid=0
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- title 組的標(biāo)題
- parentGid 父組的ID, 如果為0表示創(chuàng)建的是根分組, 如果大于0,表示創(chuàng)建該組下的一個(gè)子組
如果操作成功,則返回
{
"status": "ok", //ok表示成功, error表示錯(cuò)誤
"gid": 1931 //gid表示新創(chuàng)建的組的ID
}
如果操作失敗,則返回
{
"status": "error",
"error": "標(biāo)題不能為空" //創(chuàng)建出錯(cuò)時(shí)的錯(cuò)誤信息
}
2、編輯組名稱¶
該接口用于編輯現(xiàn)有組的名稱,接口如下:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.renameGroup&format=raw
參數(shù):
code=權(quán)限碼&title=組標(biāo)題&gid=0
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- title 組的新標(biāo)題
- gid 要修改組的ID, 要求大于0
如果操作成功,則返回
{
"status": "ok", //ok表示成功, error表示錯(cuò)誤
"gid": 1931, //gid表示組的ID
"oldTitle": "數(shù)學(xué)1" //表示原組的標(biāo)題
}
如果操作失敗,則返回
{
"status": "error",
"error": "標(biāo)題不能為空" //創(chuàng)建出錯(cuò)時(shí)的錯(cuò)誤信息
}
3、刪除組¶
該接口用于刪除某一個(gè)組,接口如下:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.delGroup&format=raw
參數(shù):
code=權(quán)限碼&gid=231
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- gid 要被刪除的組的ID, 要求大于0
如果操作成功,則返回
{
"status": "ok", //ok表示成功, error表示錯(cuò)誤
}
如果操作失敗,則返回
{
"status": "error",
"error": "不正確的組ID, 請(qǐng)確認(rèn)是否有權(quán)限修改該組的信息" //創(chuàng)建出錯(cuò)時(shí)的錯(cuò)誤信息
}
4、移動(dòng)組¶
移動(dòng)組用于把一個(gè)組移動(dòng)成另一個(gè)組的子組, 接口如下
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.mvGroup&format=raw
參數(shù):
code=權(quán)限碼&gid=112&mvToGid=23
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- gid 要被移動(dòng)的組的ID, 要求大于0
- mvToGid 要移動(dòng)到的組ID
如果操作成功,則返回
{
"status": "ok", //ok表示成功, error表示錯(cuò)誤
}
如果操作失敗,則返回
{
"status": "error",
"error": "不正確的組ID, 請(qǐng)確認(rèn)是否有權(quán)限修改該組的信息" //創(chuàng)建出錯(cuò)時(shí)的錯(cuò)誤信息
}
5、獲取組列表¶
返回某一組(或所有組)下所有子組信息, 接口如下
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.lsGroups&format=raw
參數(shù):
code=權(quán)限碼&gid=112
- code 每個(gè)賬戶唯一對(duì)應(yīng)的驗(yàn)證碼,string類型。
- gid 可選參數(shù), 如果設(shè)置了該參數(shù),則列出的是該組下的所有子組的信息。如果gid為0或者沒有設(shè)置,則表示列出所有根路徑下的組數(shù)據(jù)
如果操作成功,則返回
{
"status": "ok", //ok表示成功, error表示錯(cuò)誤,
"data": [
{
"gid": 1312, //組ID
"title": "組標(biāo)題", //組的標(biāo)題
},
{
"gid": 1332, //組ID
"title": "組標(biāo)題", //組的標(biāo)題
}
...
]
}
如果操作失敗,則返回
{
"status": "error",
"error": "不正確的組ID, 請(qǐng)確認(rèn)是否有權(quán)限修改該組的信息" //創(chuàng)建出錯(cuò)時(shí)的錯(cuò)誤信息
}