“成绩云接口开发文档”的版本间的差异

2022年6月27日 (一) 10:00的最后版本

前言

本文档针对需要对接成绩云系统的平台而编写。

接入成绩云的平台需要先联系知未科技研发，获取2个基本参数：平台ID[platform]，平台密钥[key]。这两个参数也可以反过来向知未科技提供。

然后提供一个接口URL前缀[apiBaseUrl]，后面所有的接口都基于这个前缀。凡是接口URL是https://chengjiyun.com前缀的，说明这个接口由第三方向成绩云发起请求。而如果接口URL前缀是[apiBaseUrl]，说明接口是由成绩云向第三方发起请求。

为每一所接入学校向知未提供一个[orgId]。

单点登录

单点登录流程说明

1. 第三方平台内添加成绩云访问单点登录链接，点击链接访问成绩云。
2. 成绩云接收来自第三方的的访问参数，查询站点信息。（成绩云是分学段建立站点的；如果一个学校包含了小学、初中、高中，那么成绩云中将分别建立小学、初中、高中三个站点。成绩云分学段建立的站点将使用第三方平台给定的学校唯一标识建立站点关联关系）。
3. 第三方平台给定的学校没有包含多个学段，则开始验证用户信息。
4. 第三方平台给定的学校包含多个学段，成绩云将会显示选择站点页面。选择站点页面将列举出访问用户可选择的站点。用户选择对应的站点后，则开始验证用户信息。

接口说明

请求方法:GET
接口方向:第三方→成绩云
PC版登录URL：https://chengjiyun.com/portal/[platform]?orgId=[orgId]&account=[account]&timestamp=[timestamp]&sign=[sign]
移动版登录URL：https://chengjiyun.com/mobile-portal/[platform]?orgId=[orgId]&account=[account]&timestamp=[timestamp]&sign=[sign]
访问参数：

查询用户

查询所有用户列表

此接口由成绩云向第三方发起请求，获取用户列表。

成绩云仅需要4种用户角色：学生，教师，管理员，家长。
此接口是下面其它接口的超集，后面的接口通过role参数查询子集。当指定了role参数后，返回结果中，可忽略用户的角色属性。

接口说明

请求方式：POST
请求URL:[apiBaseUrl]/queryUsers
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_01",
            "studentId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": "1",
            "roleList": [
                "学生"
            ]
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "roleList": [
                "管理员",
                "教师"
            ]
        },
        {
            "account": "parent_01",
            "name": "费曼",
            "roleList": [
                "家长"
            ]
        },
    ]
}

查询学生列表

此接口由成绩云向第三方发起请求，获取学生用户列表。

接口说明

请求方式：POST
请求URL: [apiBaseUrl]/queryUsers
请求参数：

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_01",
            "studentId": "20190101",
            "name": "刘备",
            "gender": "男",
            "grade": 10,
            "class": "1"
        },
        {
            "account": "zhiwei_02",
            "studentId": "20190102",
            "name": "关羽",
            "gender": "男",
            "grade": 11,
            "class": "2"
        },
        {
            "account": "zhiwei_03",
            "studentId": "20190103",
            "name": "张飞",
            "gender": "男",
            "grade": 12,
            "class": "3"
        }
    ]
}

查询管理员列表

此接口由成绩云向第三方发起请求，获取管理员用户列表。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryUsers
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_07",
            "name": "陈大文"
        },
        {
            "account": "zhiwei_08",
            "name": "张伟"
        },
        {
            "account": "zhiwei_09",
            "name": "杨红"
        }
    ]
}

查询教师列表

此接口由成绩云向第三方发起请求，获取教师用户列表。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryUsers
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "zhiwei_04",
            "name": "孔明"
        },
        {
            "account": "zhiwei_05",
            "name": "郭嘉"
        },
        {
            "account": "zhiwei_06",
            "name": "单福"
        }
    ]
}

查询家长列表

此接口由成绩云向第三方发起请求，获取家长用户列表。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryUsers
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "account": "parent_01",
            "name": "费曼",
            "studentList": [
                "stu_01"
            ]
        },
        {
            "account": "parent_02",
            "name": "图灵",
            "studentList": [
                "stu_02",
                "stu_03"
            ]
        },
        {
            "account": "parent_03",
            "name": "香侬",
            "studentList": [
                "stu_04",
                "stu_05",
                "stu_06"
            ]
        }
    ]
}

管理用户

新增用户

第三方平台新增用户信息后，主动推送新增的用户到成绩云，通知成绩云新增相应用户。

接口说明

请求方式：POST（Content-Type:application/json）
接口方向:第三方→成绩云
请求url: https://chengjiyun.com/vendor-api/addUser?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明（并非所有角色都支持全部参数）:

POST数据结构参数:

请求样例

POST数据如下：

    [
        {
            "account": "zhiwei_01",
            "name": "刘备",
            "class": "2",
            "roleList": [
                 "管理员",
                 "教师",
            ]
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "gender": "男",
            "roleList": [
                 "教师",
            ]
        },
        {
            "account": "student_01",
            "name": "费曼",
            "grade": 7,
            "class": "1",
            "roleList": [
                 "教师",
            ]
        }
    ]

返回样例

{
    "code": 0,
    "msg": "成功",
}

删除用户

第三方平台删除用户信息后，主动推送删除的用户到成绩云，通知成绩云进行删除。

接口说明

请求方式：POST（Content-Type:application/json）
接口方向:第三方→成绩云
请求url: https://chengjiyun.com/vendor-api/deleteUser?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

POST数据结构参数:

请求样例

POST数据如下：

   [
      "zhiwei_01",
      "zhiwei_06",
      "parent_01"
   ]

返回样例

{
    "code": 0,
    "msg": "成功",
}

更新用户

第三方平台修改用户信息后，主动推送被修改用户到成绩云进行修改。

接口说明

请求方式：POST（Content-Type:application/json）
接口方向:第三方→成绩云
请求url: https://chengjiyun.com/vendor-api/updateUser?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

POST数据结构参数（并非所有角色都支持全部参数的修改，例如班别信息对家长角色是无效的）:

请求样例

POST数据如下：

    [
        {
            "account": "zhiwei_01",
            "name": "刘备",
            "class": "2",
            "status": 1
        },
        {
            "account": "zhiwei_06",
            "name": "单福",
            "gender": "男",
            "status": 0
        },
        {
            "account": "parent_01",
            "name": "费曼"
        },
    ]

返回样例

{
    "code": 0,
    "msg": "成功",
}

查询班级任教信息列表

成绩云向第三方平台发起请求，查询班级任教信息。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryClassStatus
请求参数：

返回参数:

{
 "语文":"zhiwei_04", 
 "数学":"zhiwei_05",
 "英语":"zhiwei_06"
}

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "year": 2018,
            "grade": 10,
            "class": "1",
            "headTeacher": "zhiwei_04",
            "courseTeacherList": {
                "语文": "zhiwei_04",
                "数学": "zhiwei_05",
                "英语": "zhiwei_06"
            }
        },
        {
            "year": 2018,
            "grade": 10,
            "class": "2",
            "headTeacher": "zhiwei_05",
            "courseTeacherList": {
                "语文": "zhiwei_04",
                "数学": "zhiwei_05",
                "英语": "zhiwei_06"
            }
        }
    ]
}

通知更新班级任教信息列表

第三方平台修改班级任教相关的数据后，需要主动通知成绩云重新读取第三方平台的数据更新。此接口无需传入更新的数据，只需通知成绩云即可。

接口说明

请求方式：GET
接口方向:第三方→成绩云
请求URL: https://chengjiyun.com/vendor-api/updateClassStatus?platform=[platform]&orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

查询考试成绩

查询考试列表

成绩云向第三方平台发起请求，获取考试列表。

接口说明

请求方式：POST
请求URL: [apiBaseUrl]/queryExam
返回格式：Content-Type:application/json
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "examId": "233",
            "title": "考试标题",
            "grade": 11 // 年级值11表示高二
        },
        {
            "examId": "234",
            "title": "考试标题",
            "grade": 12 // 年级值12表示高三
        }
    ]
}

查询单次考试总分成绩

成绩云向第三方平台发起请求，获取单次考试详细成绩数据。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryExamDetail
返回格式：Content-Type:application/json
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "studentId": "20180101",
            "scores": {
                "语文": 120,
                "数学": 118,
                "英语": 121,
                "物理": 89,
                "化学": 78,
                "生物": 88,
                "政治": 78,
                "历史": 85,
                "地理": 83
            }
        },
        {
            "studentId": "20180102",
            "scores": {
                "语文": 118,
                "数学": 136,
                "英语": 98
            }
        }
    ]
}

查询单次考试小题分科目列表

成绩云向第三方平台发起请求，获取考试小题分列表。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryQuestionList
返回格式：Content-Type:application/json
请求参数:

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": 
        {
            "examId": "233",
            "courses": [
               "语文",
               "数学",
            ],
        }
}

查询单次考试小题分试卷结构

成绩云向第三方平台发起请求，获取单次考试某一科目小题分试卷结构。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryQuestionStructure
请求参数：

返回参数:
下面参数的具体定义，请阅读理解 试卷结构

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "number": "1",
            "answerType": "客观题",
            "score": 5,
            "scroll": "一卷",
            "group": "A1",
            "questionType": "基础选择",
            "knowledge": "语文基础知识",
            "ability": "掌握"
        },
        {
            "number": "2",
            "answerType": "主观题",
            "score": 10,
            "scroll": "二卷",
            "group": null,
            "questionType": "现代文阅读",
            "knowledge": null,
            "ability": null
        }
    ]
}

查询单次考试小题分成绩

成绩云向第三方平台发起请求，获取单次考试某一科目小题分所有学生分数。

接口说明

请求方式：POST
请求url: [apiBaseUrl]/queryQuestionScore
请求参数：

返回参数:
下面参数的具体定义，请阅读理解 试卷结构

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "studentId": "20210101",
            "scores": {
                "1": 5,
                "2": 8,
                "3.a": 4.5,
                "3.b": 3
            }
        },
        {
            "studentId": "20210102",
            "scores": {
                "1": 5,
                "2": 2,
                "3.a": null,
                "3.b": 4
            }
        }
    ]
}

常见问题

附录

签名参数sign生成说明

第一步：对传入的参数按照键名排序
第二步：使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA
第三步：在stringA最后拼接上“&key=[平台密钥]”得到stringSignTemp字符串，并对stringSignTemp进行MD5运算
第四步：得到最终请求字符串sign

PHP签名算法示例:

//$key 平台密钥
function sign($data, $key) {
  ksort($data);                                    // 正向排序
  $key_str = urldecode(http_build_query($data));  // 连接字符串
  $key_str .= '&key=' . $key;                     // 拼接key
  return md5($key_str);
}

$data = array(
   'orgId'=>'testapi',
   'account'=> 'zhiwei_01',
   'type'=> '高中',
   'timestamp'  => time(),
);
$sign = sign($data, $key);

注意：一般接口会有一个timestamp参数，如无特别说明，timestamp的有效时间为600秒（登录接口有效时常为7200秒），超过该时长请求无效，以降低受到重放攻击的风险。此时长在实际使用中可能会做出调整，请尽可能地使用实时时间。

返回结果

返回示例：

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "userName": "成绩云",
            "studentId": 101,
        }
    ]
}

公共返回码

开发者每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返回码信息调试接口，排查错误。 返回码如下: