考生数据管理¶
注： 所有接口只针对黄金会员提供，非黄金会员无法调用
字段管理¶
获取考生字段信息， 接口如下：
GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getStudentFields&format=raw
code=权限码
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
返回数据：
[
{
"sFid":1,// 字段id，int类型
"label": "姓名", //字段标题， string类型
"isLoginField": false, //是否为登录字段，只能存在一个登录字段，不存在或等于false为普通字段，boolean类型
}
]
正常返回的数据如下：
[
{
"sFid": 1,
"sLabel": "姓名"
},
{
"sFid": 2,
"sLabel": "性别"
},
{
"sFid": 4,
"sLabel": "手机"
},
{
"sFid": 5,
"sLabel": "身份证"
},
{
"sFid": 10,
"sLabel": "密码"
},
//以上字段为系统默认字段，实际可能存在更多字段，请以实际获取的对象为准
...
]
字段的添加和修改请到系统的考生管理中处理
考生管理¶
考生管理接口提供了添加、修改、删除考生信息的功能，具体接口信息如下
添加考生¶
通过该接口，可以添加一个或多个考生。
接口如下所示：
POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.addStudentsV2&format=raw
参数：
code=权限码
students=[ //考生数组，每个元素对象代表一个考生
{ //代表一个考生信息对象
"gid": 11, //考生所属组的id
"fields": [ //考生信息
{
"sFid": 1, // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
"value":"王二" //考生字段的值，如sFid的值为1，这里则填写姓名
},
...
{
"sFid": 4, // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
"value":"13800000000" //考生字段的值，如sFid的值为4，这里则填写手机号码
}
]
},
...
{ //代表一个考生信息对象
"gid": 11, //考生所属组的id
"fields": [ //考生信息
{
"sFid": 1, // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
"value":"张三" //考生字段的值，如sFid的值为1，这里则填写姓名
},
...
{
"sFid": 4, // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
"value":"13800000001" //考生字段的值，如sFid的值为4，这里则填写手机号码
}
]
}
]
参数说明：
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
- students 表示要添加的考生信息， 其中gid表示这个考生要加入到哪个组，如果是多个组，请用逗号分隔的字符串表示。 fields表示考生的信息项。
该接口返回成功添加的考生sid
{
"status": "ok", //成功返回 ok，失败返回 error
"success": [ //成功添加的数据，每个元素都是对象，sid表示考生id, index表示要添加考生的数据索引
{
"sid":123,
"index":1
},
{
"sid":125,
"index":2
}
],
"fail": [3,4,5] //fail表示失败的考生索引
}
修改考生信息¶
通过该接口，可以修改一个或多个考生的信息
接口如下所示：
POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.updateStudents&format=raw
参数：
code=权限码
stuInfo=[ //考生数组，每个元素对象代表一个考生
{ //代表一个考生信息对象
"sid": 11, //考生id，id和登录值不能同时为空，必须填写一个
"loginValue":"小明" //考生登录值，id和登录值不能同时为空，必须填写一个
"fields": [ //考生信息
{
"sFid": 1, // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
"value":"王二" //考生字段的值，如sFid的值为1，这里则填写姓名
},
]
},
]
参数说明：
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
- stuInfo 表示要更新的考生信息， sid表示考生ID, loginValue表示考生登录值， fields表示考生的字段信息
该接口返回成功修改的考生sid或登录值
{
"status": "ok", //成功返回 ok，失败返回 error
"success": [1,2], //表示成功的考生id或登录值
"fail": [3,4,5] //fail表示失败的考生id或登录值
}
删除考生¶
使用该接口删除一个或多个考生。 接口如下所示：
POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.delStudents&format=raw
参数：
code=权限码
loginValues=["1000","10001"] //考生登录值列表，字符串数组，id和登录值二选一，优先读取登录值
参数说明：
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
- loginValues 表示要删除的考生登录值列表
该接口返回成功删除的考生sid或登录值
{
"status": "ok", //成功返回 ok，失败返回 error
"success": [1,2], //表示成功的考生sid或登录值
"fail": [3,4,5] //fail表示失败的考生的sid或登录值
}
失败则返回：
{
"status": "error", //成功返回 ok，失败返回 error
"error": "无效的sid" //error为失败的错误信息
}
移动考生到组¶
使用该接口移动一个或多个考生到一个或多个组。 接口如下所示：
POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.mvStudents&format=raw
参数：
code=权限码
mvStuInfo={
"gids": [22,33], //如果gids里有多个值，则表示把考生添加到这些组（PS 一个考生允许同时存在多个组)
"loginValues":["小明","小红"] //考生登录字段值，字符串数组
"action": "addto|moveto" //操作， addto表示添加到组，这个时候一个考生可能存在多个组， moveto表示移动到组，这个时候考生只存在一个组。如果action值为moveto,则gids只能为一个，如果有多个gid, 只取第一个
}
参数说明：
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
- mvStuInfo 表示要移动的数据信息
该接口返回成功添加的考生loginValue
{
"status": "ok", //成功返回 ok，失败返回 error
"success": [1,2], //表示成功的考生登录字段值
"fail": [3,4,5] //fail表示失败的考生登录字段值
}
失败则返回：
{
"status": "error", //成功返回 ok，失败返回 error
"error": "无效的sid" //error为失败的错误信息
}
获取考生信息¶
使用该接口获取一个或多个考生的信息 接口如下所示：
POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getStudentsInfo&format=raw
参数：
code=权限码
loginValues=[13212,2382,392]
参数说明：
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
- loginValues 表示考生登录字段值列表
一次最多只能查10个考生的信息
该接口成功则返回
{
"status": "ok", //成功返回 ok，失败返回 error
"data": [
{
"loginValue":"王二",//考生登录值，若请求的是loginValues,则返回loginValue
"fields":[
{
"sFid":1,
"label":"姓名",
"value": "王二"
},
{
"sFid":13,
"label":"单位",
"value": "全部门"
}
],
"group": [
"gid": 123, //组的ID
"title": "英文学习小组" //组名称
]
},
{
"loginValue": 3925, //考生的ID
"loginValue":"张三",//考生登录值，若请求的是loginValues,则返回loginValue
"fields":[
{
"sFid":1,
"label":"姓名",
"value": "张三"
},
{
"sFid":13,
"label":"单位",
"value": "全部门"
}
],
"group": [
"gid": 123, //组的ID
"title": "英文学习小组" //组名称
]
}
]
}
失败则返回：
{
"status": "error", //成功返回 ok，失败返回 error
"error": "无效的sid" //error为失败的错误信息
}
如有问题，请随时联系我们客服
获取考生列表¶
使用该接口获取考生列表 接口如下所示：
POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getStudents&format=raw
参数：
code=权限码
start=0
limit=30
参数说明：
- code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
- start 用于数据量很大时的分页显示，表示分页的数据偏移， 默认为0， 可选参数
- limit 用于数据量很大时的分布显示，设置每页的数据显示数量，默认为30， 可选参数
该接口成功则返回
{
{
"loginValue": "90068", //考生登录字段值
"fields": [ //考生的信息项
{
"label": "姓名",
"sFid": "1",
"value": "我是从api添加的考生8888"
},
{
"label": "邮箱",
"sFid": "3",
"value": "54457@qq.com"
},
{
"label": "密码",
"sFid": "10",
"value": "123456"
}
]
},
{
"loginValue": "90067",
"fields": [
{
"label": "姓名",
"sFid": "1",
"value": "我是从api添加的考生55555"
},
{
"label": "邮箱",
"sFid": "3",
"value": "4544@qq.com"
},
{
"label": "密码",
"sFid": "10",
"value": "123456"
}
]
}
}
没有考生记录则返回：
{
"status": "ok",
"message": "empty"
}
如有问题，请随时联系我们客服