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

来自成绩云帮助中心
跳转至： 导航、 搜索
（→‎查询学生列表）
（→‎查询管理员列表）
第312行： 第312行：
 
| style="width:150px; text-align:center;" | 描述
 
| style="width:150px; text-align:center;" | 描述
 
|-
 
|-
−
|id
+
|account
 
|string
 
|string
−
|管理员的账户 ID
+
|账号
 
|-
 
|-
 
|name
 
|name
第328行： 第328行：
 
     "data": [
 
     "data": [
 
         {
 
         {
−
             "id": "zhiwei_07",
+
             "account": "zhiwei_07",
 
             "name": "陈大文"
 
             "name": "陈大文"
 
         },
 
         },
 
         {
 
         {
−
             "id": "zhiwei_08",
+
             "account": "zhiwei_08",
 
             "name": "张伟"
 
             "name": "张伟"
 
         },
 
         },

2019年3月5日 (二) 13:55的版本

前言

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

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

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

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

单点登录

Login.png


单点登录流程说明


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]
访问参数：

参数 类型 是否必填 描述
orgId string 是 学校ID
account string 是 账号
type string 否 学段，可选值为“小学”、“初中”、“高中”。如果存在多学段且不填此字段，系统会让用户选择。
timestamp int 是 时间戳（Unixtime），有效时长7200秒
sign string 是 签名, 详见附录签名参数sign生成说明

查询用户

查询所有用户列表

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

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

接口说明

请求方式：GET
请求URL:[apiBaseUrl]/queryUsers?orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校 ID
role string 否 角色。可选值为“学生”、“教师”、“管理员、“家长”
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
name string 姓名
roleList array 角色数组
schoolId string 学号。要求同一个学校内唯一
gender string 性别，可选“男”、“女”或“”（空字符串）
grade int 年级，7表示初一，10表示高一，以此类推。
class int 班级。必须为纯整数，不能含有其他字符

返回样例 

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


查询学生列表

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

接口说明

请求方式：GET
请求URL: [apiBaseUrl]/queryUsers?orgId=[orgId]&timestamp=[timestamp]&role=学生&sign=[sign]
请求参数：

参数 类型 是否必填 描述
orgId string 是 学校 ID
role string 是 填“学生”
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
schoolId string 学号。要求同一个学校内唯一
name string 姓名
gender string 性别，可选“男”、“女”或“”（空字符串）
grade int 年级
class int 班级。必须为纯整数，不能含有其他字符

返回样例 

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

查询管理员列表

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryUsers?orgId=[orgId]&timestamp=[timestamp]&role=管理员&sign=[sign]
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校 ID
role string 是 填“管理员”
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 账号
name string 姓名

返回样例 

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


查询教师列表

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryUsers?orgId=[orgId]&timestamp=[timestamp]&role=教师&sign=[sign]
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校 ID
role string 是 填“教师”
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
id string 教师的账户 ID
name string 姓名


返回样例 

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

查询家长列表

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryUsers?orgId=[orgId]&timestamp=[timestamp]&role=家长&sign=[sign]
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校 ID
role string 是 填“家长”
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
id string 家长的账户 ID
name string 姓名
studentList array 家长关联的学生 ID数组


返回样例 

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": "parent_01",
            "name": "费曼",
            "studentList": [
                "stu_01"
            ]
        },
        {
            "id": "parent_02",
            "name": "图灵",
            "studentList": [
                "stu_02",
                "stu_03"
            ]
        },
        {
            "id": "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参数说明（并非所有角色都支持全部参数，例如班别信息对家长角色是无效的）:

参数 类型 是否必填 描述
platform string 是 平台ID
orgId string 是 学校ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录签名参数sign生成说明

POST数据结构参数:

参数 类型 是否必填 描述
id string 是 用户的唯一 id
roleList array 是 角色（支持管理员、教师、家长、学生）
name string 是 姓名
schoolId string 否 学号。要求同一个学校内唯一
gender string 否 性别，可选“男”、“女”或“”（空字符串）
grade int 否 年级，7表示初一，10表示高一，以此类推。
class int 否 班级。必须为纯整数，不能含有其他字符

请求样例

POST数据如下： 

    [
        {
            "id": "zhiwei_01",
            "name": "刘备",
            "class": 2,
            "roleList": [
                 "管理员",
                 "教师",
            ]
        },
        {
            "id": "zhiwei_06",
            "name": "单福",
            "gender": "男",
             "roleList": [
                 "教师",
            ]
        },
        {
            "id": "parent_01",
            "name": "费曼",
             "roleList": [
                 "学生",
            ]
        }
    ]



返回样例 

{
    "code": 0,
    "msg": "success",
}


删除用户

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

接口说明

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

参数 类型 是否必填 描述
platform string 是 平台ID
orgId string 是 学校ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录签名参数sign生成说明

POST数据结构参数:

参数 类型 是否必填 描述
id string 是 用户的唯一 id

请求样例

POST数据如下： 

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



返回样例 

{
    "code": 0,
    "msg": "success",
}


更新用户

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

接口说明

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

参数 类型 是否必填 描述
platform string 是 平台ID
orgId string 是 学校ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录签名参数sign生成说明

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

参数 类型 是否必填 描述
id string 是 用户的唯一 id
name string 否 姓名
schoolId string 否 学号。要求同一个学校内唯一
gender string 否 性别，可选“男”、“女”或“”（空字符串）
grade int 否 年级，7表示初一，10表示高一，以此类推。
class int 否 班级。必须为纯整数，不能含有其他字符

请求样例

POST数据如下： 

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



返回样例 

{
    "code": 0,
    "msg": "success",
}


查询班级任教信息列表

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryClassStatus?orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
请求参数：

参数 类型 是否必填 描述
orgId string 是 学校 ID
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
year int 入学年份
grade int 年级
class int 班级。必须为纯整数，不能含有其他字符
headTeacher string 班主任的账户 ID
subject enum(0,1,2) 0=>未指定，1=>文科， 2=>理科
courseTeacherList object 科目任教信息. 以科目的中文名为属性名, 教师的账户 ID 为 属性值的结构对象

例如： 

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

返回样例 

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

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

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

接口说明

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

参数 类型 是否必填 描述
orgId string 是 学校ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名。详见附录签名参数sign生成说明

查询考试成绩

查询考试列表

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

接口说明

请求方式：GET
请求URL: [apiBaseUrl]/queryExam?orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
返回格式：Content-Type:application/json
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 是否允许为 null 描述
examId string 否 考试ID
title string 否 考试标题
grade int 是 年级(可取值1,2,3,4,5,6,7,8,9,10,11,12)
year int 是 入学年份(学生入学时的年份)


返回样例 

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "examId": "233",
            "title": "考试标题",
            "grade": 11,
            "year": 2017,
        },
        {
            "examId": "234",
            "title": "考试标题",
            "grade": 11,
            "year": 2017,
        }
    ]
}

查询单次考试总分成绩

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryExamDetail?orgId=[orgId]&timestamp=[timestamp]&sign=[sign]
返回格式：Content-Type:application/json
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校ID
examId string 是 考试ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 描述
account string 学生账号
scores array 科目成绩


返回样例 

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

查询考试小题分科目列表

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryQuestionList?orgId=[orgId]&timestamp=[timestamp]&examId=[examId]&sign=[sign]
返回格式：Content-Type:application/json
请求参数:

参数 类型 是否必填 描述
orgId string 是 学校ID
examId string 是 考试ID
timestamp int 是 时间戳（Unixtime），有效时长600秒
sign string 是 签名。详见附录签名参数sign生成说明

返回参数:

参数 类型 是否允许为 null 描述
examId string 否 考试ID
courses array 否 有分析小题分的科目集合


返回样例 

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

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

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryQuestionStructure?orgId=[orgId]&examId=[examId]&course=[course]&timestamp=[timestamp]&sign=[sign]
请求参数：

参数 类型 是否必填 描述
orgId string 是 学校 ID
examId string 是 考试 ID
course string 是 科目的中文名
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

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

参数 类型 是否允许为 null 描述
number string 否 题号
subjective enum("主观题"，"客观题") 否 类型
score float 否 满分值
scroll enum("一卷"，"二卷") 否 卷别
selection string 是 选做题分组
type string 是 题型
knowledge string 是 知识点
ability string 是 能力

返回样例 

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "number": "1",
            "subjective": "客观题",
            "score": 5,
            "scroll": "一卷",
            "selection": "A1",
            "type": "基础选择",
            "knowledge": "语文基础知识",
            "ability": "掌握"
        },
        {
            "number": "2",
            "subjective": "主观题",
            "score": 10,
            "scroll": "二卷",
            "selection": null,
            "type": null,
            "knowledge": null,
            "ability": null
        }
    ]
}

查询单次考试小题分成绩

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

接口说明

请求方式：GET
请求url: [apiBaseUrl]/queryQuestionScore?orgId=[orgId]&examId=[examId]&course=[course]&timestamp=[timestamp]&sign=[sign]
请求参数：

参数 类型 是否必填 描述
orgId string 是 学校 ID
examId string 是 考试 ID
course string 是 科目的中文名
timestamp int 是 时间戳（Unixtime）
sign string 是 签名。详见附录签名参数sign生成说明

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

参数 类型 是否允许为 null 描述
account string 否 学生账户 ID
scores hash 是 题号: 分数。分数为 null 时, 表示学生缺答

返回样例 

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "account": "zhiwei_01",
            "scores": {
                "1": 5,
                "2": 8,
                "3.a": 4.5,
                "3.b": 3
            }
        },
        {
            "account": "zhiwei_02",
            "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 int 公共返回码，详见附录公共返回码
msg string 返回信息
data object 返回的查询或操作数据,数据可能是对象或数组。具体根据每个API而定。

返回示例： 

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

公共返回码

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

返回码(code) 消息(msg)
0 成功
10001 未知错误
10002 服务器忙
10003 服务器无响应
10004 操作超时
10005 网络异常
10006 IP地址无效或不匹配
10007 操作异常
10008 操作无效
10009 数据库操作异常
20001 没有匹配的数据
20002 数据无效
30001 接口不存在
30002 参数解析错误
30003 参数格式错误
30004 参数长度超出范围
30005 参数值内容错误
30006 验证失败
40001 用户账号不存在
40002 用户账号已经禁用
取自“https://chengjiyun.com/wiki/index.php?title=成绩云接口开发文档&oldid=1622”