成绩云接口开发文档

来自成绩云帮助中心
Bolun（讨论 | 贡献）2019年1月10日 (四) 16:35的版本 （→‎常见问题）

跳转至： 导航、 搜索

前言

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

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

然后提供一个接口URL前缀[apiBaseUrl]，后面所有的接口都基于这个前缀。

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

单点登录

Login.png


单点登录流程说明：

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

单点登录链接： 

 [apiBaseUrl]/[paltform]?orgId=[学校ID]&account=[账号]&type=[角色]&timestamp=[当前时间戳]&sign=[加密串]

paltform:平台ID
请求方法:GET
接口方向:第三方→成绩云
访问参数：

访问参数
参数 类型 是否必填 描述
orgId string 是 学校ID
account string 是 账号
type string 是 角色
timestamp int 是 时间戳time()
sign string 是 加密串, 详见附录签名参数sign生成说明

查询用户

查询所有用户列表

此接口是下面其它接口的超集，后面的接口通过role参数查询子集。

请求方式：POST
请求示例: [apiBaseUrl]/queryUsers?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN

访问参数
参数 类型 是否必填 描述
orgId string 是 学校的唯一 id


返回样例 

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "zhiwei_01",
            "name": "刘备",
            "roleList": [
                "学生"
            ]
        },
        {
            "id": "zhiwei_02",
            "name": "关羽",
            "roleList": [
                "学生"
            ]
        },
        {
            "id": "zhiwei_04",
            "name": "孔明",
            "roleList": [
                "教师"
            ]
        },
        {
            "id": "zhiwei_05",
            "name": "郭嘉",
            "roleList": [
                "教师"
            ]
        },
        {
            "id": "zhiwei_06",
            "name": "单福",
            "roleList": [
                "管理员",
                "教师"
            ]
        },
        {
            "id": "parent_01",
            "name": "费曼",
            "roleList": [
                "家长"
            ]
        },
        {
            "id": "parent_02",
            "name": "图灵",
            "roleList": [
                "家长"
            ]
        }
    ]
}


返回参数
参数 类型 描述
id string 学生在平台内的唯一 id
schoolId string 学号。要求同一个学校内唯一
name string 姓名
roleList array 角色数组


查询学生列表

请求方式：POST
请求示例: [apiBaseUrl]/queryStudents?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN

请求参数
参数 类型 是否必填 描述
orgId string 是 学校 id


返回样例 

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


返回参数
参数 类型 描述
id string 学生在平台内的唯一 id
schoolId string 学号。要求同一个学校内唯一
name string 姓名
gender enum ("男", "女") 性别
grade int 年级
class int 班级。必须为纯整数，不能含有其他字符

查询管理员列表

请求方式：POST
请求示例: [apiBaseUrl]/queryAdmins?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN

访问参数
参数 类型 是否必填 描述
orgId string 是 学校的唯一 id


返回样例 

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


返回参数
参数 类型 描述
id string 平台内的唯一 id
name string 姓名

查询教师列表

请求方式：POST
请求示例: [apiBaseUrl]/queryTeachers?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN

访问参数
参数 类型 是否必填 描述
orgId string 是 学校的唯一 id


返回样例 

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


返回参数
参数 类型 描述
id string 平台内的唯一 id
name string 姓名

查询家长列表

请求方式：POST
请求示例: [apiBaseUrl]/querys?orgId=ORGID&timestamp=TIMESTAMP&sign=SIGN

访问参数
参数 类型 是否必填 描述
orgId string 是 学校的唯一 id


返回样例 

{
    "code": 0,
    "msg": "成功",
    "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"
            ]
        }
    ]
}


返回参数
参数 类型 描述
id string 家长在平台内的唯一 id
name string 姓名
studentList array 家长关联的学生 id数组

更新用户

查询班级任教信息列表

更新班级任教信息列表

常见问题

附录

签名参数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'=> 2345,
   'account'=> 4567,
   'type'=> 1,
   'timestamp'  => time(),
);
$sign = sign($data, $key);

返回结果

参数名称 类型 描述
code int 公共返回码，详见附录公共返回码
msg string 返回信息
data object 返回的查询或操作数据,数据可能是对象或数组。具体根据每个API而定。

返回示例： 

{
    "code": "10000",
    "msg": "成功",
    "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=1414”