局域网考试系统接口文档¶
单点登录¶
注: 所有接口仅针对旗舰会员或以上会员级别提供,非旗舰会员及以上无法调用,所有开放平台接口默认共享10QPS。
单点登录允许考生只在用户的系统上登录一次,点击试卷考试时不再需要再次登录, 例如用户A有公司自己的OA系统, 考生王二登录到公司的OA系统后, 在系统里点开始考试,这时王二就不再需要输入自己的账号,而是直接就进入考试了。
1、单点登录考试¶
单点登录考试允许用户考生直接在用户系统上点击就开始考试, 不再需要额外的身份认证, 接口如下:
请求
GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.newStudentSSO&format=raw
请求数据
code=权限码&loginValue=登录字段的值&password=密码&eid=试卷ID
- code 每个账户唯一对应的验证码,string类型,该值可联系优考试获取
- loginValue 表示的是考生的登录值,比如说系统设置了使用手机登录,那么这里就是考生的手机号码。
- password 考生的密码,如果有的话;如果考生没有的话,这里留空
- eid 考生要做的试卷ID
登录成功后,系统会自动跳转到考试界面,且不需要再执行身份验证
2、单点登录考生后台¶
单点登录到考生后台和单点登录考试原理一样, 差别是不传eid参数或传0. 即:
GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.newStudentSSO&format=raw&loginValue=13487361736&password=1294783&eid=0
系统判断eid为0时会自动跳转到考生后台界面
3、子管理员单点登录¶
子管理员单点登录管理后台, 接口如下:
请求
GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.childAdminSSO&format=raw
请求数据
code=权限码&email=邮箱&password=密码
- code 每个账户唯一对应的验证码,string类型,该值可联系优考试获取
- email 子管理员邮箱,必填
- password 子管理员密码,必填
登录成功后,系统会自动跳转到管理后台
获取考生成绩¶
注: 所有接口只针对旗舰会员提供,非旗舰会员无法调用,所有开放平台接口默认共享10QPS
1、获取某一考生参与考试的记录¶
通过该接口,可以获取考生在某一份试卷下的考生成绩。
接口如下所示:
GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.queryResults&format=raw
参数:
code=权限码&eid=试卷ID&loginValues=考生登录字段值&start=0&limit=30
参数说明:
- code 每个账户唯一对应的验证码,string类型,该值可联系优考试获取
- eid 表示试卷ID
- loginValues 表示的是考生的登录值,可选参数,比如说系统设置了使用手机登录,那么这里就是考生的手机号码
- year 用于查询不同年份的数据,默认为当前年份 例:2022,可选参数
- start 用于数据量很大时的分页显示,表示分页的数据偏移, 默认为0, 可选参数
- limit 用于数据量很大时的分布显示,设置每页的数据显示数量,默认为30, 可选参数
该接口返回考生在这个试卷里的所有考试记录信息
[
{
"viewResult":"https://ks.youkaoshi.cn/viewresult/token",//查看详细考试详情的链接,有30分钟时间限制,超过30分钟后得重新获取链接
"score": 30,//考试得分,float类型
"startTime": 1539075728,//考生开始作答的时间戳,int类型,单位s(秒)
"endTime": 1539075828,//考生交卷的时间戳,int类型,单位s(秒)
"status": 1,//status 表示答卷状态,1表示正常交卷, 0正在考试中,2表示超时自动交卷,3表示被管理员强制交卷,4表示系统执行交卷
},
{
"viewResult":"https://ks.youkaoshi.cn/viewresult/token",//查看详细考试详情的链接,有30分钟时间限制,超过30分钟后得重新获取链接
"score": 32,//考试得分,float类型
"startTime": 1539075628,//考生开始作答的时间戳,int类型,单位s(秒)
"endTime": 1539075828,//考生交卷的时间戳,int类型,单位s(秒)
"status": 1,//status 表示答卷状态,1表示正常交卷, 0正在考试中,2表示超时自动交卷,3表示被管理员强制交卷,4表示系统执行交卷
},
]
2、获取参与考试的所有考试记录信息¶
如果没有指定 loginValues 的话, 则返回的是所有参与该试卷考试的考试记录数据
[
{
"viewResult":"https://ks.youkaoshi.cn/viewresult/token",//查看详细考试详情的链接,有30分钟时间限制,超过30分钟后得重新获取链接
"score": 30,//考试得分,float类型
"startTime": 1539075728,//考生开始作答的时间戳,int类型,单位s(秒)
"endTime": 1539075828,//考生交卷的时间戳,int类型,单位s(秒)
"loginValues": 19382,
"name": "王二"
},
{
"viewResult":"https://ks.youkaoshi.cn/viewresult/token",//查看详细考试详情的链接,有30分钟时间限制,超过30分钟后得重新获取链接
"score": 32,//考试得分,float类型
"startTime": 1539075628,//考生开始作答的时间戳,int类型,单位s(秒)
"endTime": 1539075828,//考生交卷的时间戳,int类型,单位s(秒)
"loginValues": 19310, //考生登录字段值
"name": "张三" //考生的姓名
},
]
3、获取试卷列表¶
试卷很多的情况下需要通过接口来动态获取试卷列表。接口如下:
GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getExams&format=raw
参数
code=权限码&start=0&limit=30
参数说明:
- code 每个账户唯一对应的验证码,string类型,该值可联系优考试获取
- start 用于数据量很大时的分页显示,表示分页的数据偏移, 默认为0, 可选参数
- limit 用于数据量很大时的分布显示,设置每页的数据显示数量,默认为30, 可选参数
返回数据:
[
{
"eid": 23812,//试卷id,int类型
"title": "测试试卷", // 试卷标题,string类型
"img": "https://fs.youkaoshi.cn/xxxxx.jpg",// 试卷封面图片链接,string类型
"url": "https://ks.youkaoshi.cn/23812", //试卷考试链接,string类型
"createTime": 1539075828,//试卷创建时间的unix时间戳,int类型,单位s(秒)
"available": 1, //试卷是否可用,int类型,1表示可用,0表示不可用
"times": 3918, //试卷的考试次数
"category": "模考" //试卷的分类名称
},
...
]
考生数据管理¶
注: 所有接口只针对旗舰会员提供,非旗舰会员无法调用,所有开放平台接口默认共享10QPS
1、获取考生字段信息¶
获取考生字段信息:
GET https://api.youkaoshi.cn/api/v1/student/getFields?code=xxx&time=当前时间戳
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"data":[
{
"sfid":1,
"label":"姓名"
},
{
"sfid":2,
"label":"性别"
},
{
"sfid":4,
"label":"手机"
},
{
"sfid":10,
"label":"密码"
}
],
"status":"ok"
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
"strconv"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/getFields"
client := &http.Client{}
fullPath := host + resource
req, _ := http.NewRequest(http.MethodGet, fullPath, nil)
time64 := time.Now().UTC().Unix()
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
q := req.URL.Query()
q.Add("code", Code)
q.Add("time", strconv.Itoa(int(time64)))
req.URL.RawQuery = q.Encode()
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
// fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
2、批量插入考生信息¶
批量插入考生信息:
POST https://api.youkaoshi.cn/api/v1/student/addStudents
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
info 要插入的数据。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"fail":[
//如插入失败,返回数据对应的下标位置
],
"status":"ok",
"success":[//插入成功的数据...
{
"sid":170603,//插入后学生的sid
"index":1 //数据所在传入数据的位置
},
{
"sid":170604,
"index":2
}
]
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/addStudents"
client := &http.Client{}
fullPath := host + resource
info := `
[
{
"gid": "2993",
"fields": [
{
"sfid": 4,
"value": "2993"
},
{
"sfid": 1,
"value": "stufor2993"
}
]
},
{
"gid": "2994",
"fields": [
{
"sfid": 10,
"value": "2994"
},
{
"sfid": 1,
"value": "stufor2994"
}
]
}
]
`
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["info"] = []string{info}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
3、批量修改考生信息¶
批量插入考生信息:
POST https://api.youkaoshi.cn/api/v1/student/changeStuinfo
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
info 要插入的数据。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"fail":[
//如失败,返回数据对应的下标位置
],
"status":"ok",
"success":[
"170603",//修改成功的sid
"170604"
]
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/changeStuinfo"
client := &http.Client{}
fullPath := host + resource
info := `
[
{
"sid":170603,
"loginValue": "",
"fields": [
{
"sfid": 1,
"value": "stufor2993change"
},
{
"sfid": 4,
"value": "18320320xxx"
}
]
},
{
"sid":170604,
"loginValue": "",
"fields": [
{
"sfid": 1,
"value": "stufor2994change"
},
{
"sfid": 10,
"value": "29944"
}
]
}
]
`
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["info"] = []string{info}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
4、批量删除考生信息¶
批量删除考生信息:
POST https://api.youkaoshi.cn/api/v1/student/delStu
参数:
code=权限码&time=当前时间戳&sids=学生唯一id(二选一字段)
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
sids(二选一) 学生唯一id。格式如下:[170603,170604] 也可参照实例代码
-
loginValues(二选一) 管理员设定的登录字段,例如名字,手机等。格式如下: ["李三","张四"] 也可参照实例代码
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"fail":[
//如失败,返回数据对应的下标位置
],
"status":"ok",
"success":[
"170603",//删除成功的sid
"170604"
]
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/delStu"
client := &http.Client{}
fullPath := host + resource
sids := "[170603,170604]"
// loginValues := "[\"登录字段xx\",\"登录字段xxx\"]"
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["sids"] = []string{sids}
// data["loginValues"] = []string{loginValues}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
5、移动考生到组¶
移动考生到组:
POST https://api.youkaoshi.cn/api/v1/student/movestugroup
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
mvStuInfo 格式请参照示例代码,在loginValues与sid中任选其一。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"fail":[
//如失败,返回数据对应的下标位置
],
"status":"ok",
"success":[
"170606",//移动成功的sid
"170607"
]
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/movestugroup"
client := &http.Client{}
fullPath := host + resource
mvStuInfo := `
{
"gids": [2993],
"loginValues":[],
"sid":[170606,170607],
"action": "moveto"
}
`
/*
上面以sid为例,如使用loginValues 格式如下 ["登录字段1","登录字段2"]
action 可以为 addto moveto delfrom
addto: 表示添加到组,这个时候一个考生可能存在多个组
moveto: 表示移动到组,这个时候考生只存在传入的组
delfrom: 表示考生从指定组移除,需注意移除后至少应还存在一个组中,否则移除失败
*/
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["mvStuInfo"] = []string{mvStuInfo}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
6、获取考生信息¶
获取考生信息:
POST https://api.youkaoshi.cn/api/v1/student/getstudentsinfo
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
loginValues(二选一字段) 管理员设定的登录字段,例如名字,手机等。格式如下: ["李三","张四"] 也可参照实例代码。
-
sids(二选一字段) 学生唯一id。格式如下:[170603,170604] 也可参照实例代码。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"data":[
{
"sid":170605,
"fields":[
{
"sFid":1,
"label":"姓名",
"value":"newstufor2993"
}
],
"group":[
{
"gid":2993,
"title":"2993"
}
]
},
{
"sid":170606,
"fields":[
{
"sFid":1,
"label":"姓名",
"value":"newstufor2994"
}
],
"group":[
{
"gid":2993,
"title":"2993"
}
]
}
],
"fail":[
//如失败,返回对应的sid或loginValues,这种情况可能是因为考生已被删除
],
"status":"ok"
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/getstudentsinfo"
client := &http.Client{}
fullPath := host + resource
// sids := "[170603,170604]"
sids := "[170605,170606]"
// loginValues := "[\"登录字段xx\",\"登录字段xxx\"]"
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["sids"] = []string{sids}
// data["loginValues"] = []string{loginValues}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
7、获取考生列表¶
获取考生列表:
POST https://api.youkaoshi.cn/api/v1/student/getstulist
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
start 分页参数。
-
limit 查询个数,最大为100。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"data":[
{
"loginValue":"newstufor2993",
"fields":[
{
"sFid":1,
"label":"姓名",
"value":"newstufor2993"
},
{
"sFid":4,
"label":"手机",
"value":"2993"
}
]
},
{
"loginValue":"newstufor2994",
"fields":[
{
"sFid":1,
"label":"姓名",
"value":"newstufor2994"
},
{
"sFid":10,
"label":"密码",
"value":"2994"
}
]
},
{
"loginValue":"newstufor29942",
"fields":[
{
"sFid":1,
"label":"姓名",
"value":"newstufor29942"
},
{
"sFid":10,
"label":"密码",
"value":"2994"
}
]
}
],
"status":"ok",
"total":12
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/getstulist"
client := &http.Client{}
fullPath := host + resource
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["start"] = []string{"0"}
data["limit"] = []string{"3"}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
8、获取所有考生或者单一考生的考试记录¶
获取考生列表:
GET https://api.youkaoshi.cn/api/v1/student/queryresults
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
start 分页参数。
-
limit 查询个数,最大为100。
-
loginValues 如需查询单个考生的考试记录,需配合eid使用。
-
eid 如需查询单个考生的考试记录,需配合loginValues使用,详见示例代码。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"data":[
{
"viewResult":"https://api.youkaoshi.cn/transgetresult?tid=xxx\u0026token=xxx", //试卷详情链接,其中 '\u0026' 为 '&' 符号, 需要转码方可正常使用。
"score":"2",//分数
"passed":"0",//考试是否及格
"status":"1",
"startTime":"1639647217",//考试考试时间
"endTime":"1639647236",//考试结束时间
"sid":"170597",
"loginValue":"n11",//登录字段
"name":"n11",//考生名字
"eid":"107264"//试卷id
},
{
"viewResult":"https://api.youkaoshi.cn/transgetresult?tid=xxx\u0026token=xxx",
"score":"1",
"passed":"0",
"status":"1",
"startTime":"1639647122",
"endTime":"1639647132",
"sid":"170597",
"loginValue":"n11",
"name":"n11",
"eid":"107264"
}
],
"status":"ok",
"total":1877
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
"strconv"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/queryresults"
client := &http.Client{}
fullPath := host + resource
req, _ := http.NewRequest(http.MethodGet, fullPath, nil)
time64 := time.Now().UTC().Unix()
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
q := req.URL.Query()
q.Add("code", Code)
q.Add("start", "0")
q.Add("limit", "2")
// ↑↑获取所有考生考试数据↑↑
// ↓↓获取单一考生参与考试的记录↓↓
// q.Add("loginValues", "n11")
// q.Add("eid", "107264")
q.Add("time", strconv.Itoa(int(time64)))
req.URL.RawQuery = q.Encode()
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
// fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
同步组织结构¶
注: 所有接口只针对旗舰会员提供,非旗舰会员无法调用,所有开放平台接口默认共享10QPS
同步考生数据可以方便的在系统之间进行考生数据交换,避免手动可能出现的错误;自动同步及时快捷,即可以同步考生信息也可以同步考生的组织结构。
1、分组管理¶
优考试通过组来管理考生,可以把组理解为班级,部门;优考试支持无限层级树状组管理,如下图所示
插入组:
POST https://api.youkaoshi.cn/api/v1/student/addcategory
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
parentGid 父节点id。 如传0,代表插入根节点。
-
title 新建组组名。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"gid":2995, //插入成功后的组id
"status":"ok"
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/addcategory"
client := &http.Client{}
fullPath := host + resource
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["parentGid"] = []string{"0"}
data["title"] = []string{"新建组"}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
2、编辑组名称¶
编辑组名称:
POST https://api.youkaoshi.cn/api/v1/student/renamegroup
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
gid 被修改组的组id。
-
title 新组名。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"gid":2995,
"oldTitle":"新建组", //旧组名
"status":"ok"
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/renamegroup"
client := &http.Client{}
fullPath := host + resource
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["gid"] = []string{"2995"}
data["title"] = []string{"新组名"}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
3、删除组¶
删除组:
POST https://api.youkaoshi.cn/api/v1/student/delGroup
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
gid 被删除组的组id。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"status":"ok"
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/delGroup"
client := &http.Client{}
fullPath := host + resource
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["gid"] = []string{"2996"}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
4、移动组¶
移动组:
POST https://api.youkaoshi.cn/api/v1/student/mvgroup
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
gid 被移动组的组id。
-
mvToGid 目标组id。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"status":"ok"
}
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/mvgroup"
client := &http.Client{}
fullPath := host + resource
time64 := time.Now().UTC().Unix()
data := make(url.Values)
data["code"] = []string{Code}
data["gid"] = []string{"2996"}
data["mvToGid"] = []string{"2995"}
data["time"] = []string{strconv.Itoa(int(time64))}
req, _ := http.NewRequest(http.MethodPost, fullPath, strings.NewReader(data.Encode()))
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}
5、获取组列表¶
获取组列表:
GET https://api.youkaoshi.cn/api/v1/student/lsgroups?code=权限码&time=当前时间戳
参数:
code=权限码&time=当前时间戳
参数说明:
-
code 每个账户唯一对应的验证码,string类型,旗舰会员及以上可在系统设置->开放平台设置中获取。
-
time 当前时间戳,例如1638768935。
-
gid(可选) 代表仅查询当前组下的子组。 如要查询所有组,不需要传该值。
-
Authorization 放到请求头的Token,详见示例代码。简单来说就是:将当前时间戳和您的code拼接起来,进行MD5加密而得。
如果操作成功,则返回:
{
"data":[
{
"gid":2989,
"title":"2989组名"
},
{
"gid":2987,
"title":"2987组名"
}
],
"status":"ok"
}
//备注:返回组列表为当前组的子组,不包括孙子组,且如某一组内没有学生,不会出现在组列表中.
如果操作失败,则返回:
接口使用示例:
package main
import (
"crypto/md5"
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
"strconv"
"time"
)
const (
Code = "xxx"
)
func main() {
host := "https://api.youkaoshi.cn"
resource := "/api/v1/student/lsgroups"
client := &http.Client{}
fullPath := host + resource
req, _ := http.NewRequest(http.MethodGet, fullPath, nil)
time64 := time.Now().UTC().Unix()
ParseToken := fmt.Sprintf("%x", md5.Sum([]byte(strconv.FormatInt(time64, 10)+Code)))
req.Header.Set("Authorization", ParseToken)
q := req.URL.Query()
q.Add("code", Code)
q.Add("gid", "2988")
q.Add("time", strconv.Itoa(int(time64)))
req.URL.RawQuery = q.Encode()
resp, err := client.Do(req)
if err != nil {
log.Println(err)
return
}
defer resp.Body.Close()
b, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Println(err)
return
}
// fmt.Println(string(b))
f, _ := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)
f.Write(b)
}