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

2019年1月11日 (五) 10:18的版本

前言

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

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

然后提供一个接口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参数查询子集。

接口说明

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

返回参数:

返回样例

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "id": "zhiwei_01",
            "name": "刘备",
            "roleList": [
                "学生"
            ]
        },
        {
            "id": "zhiwei_06",
            "name": "单福",
            "roleList": [
                "管理员",
                "教师"
            ]
        },
        {
            "id": "parent_01",
            "name": "费曼",
            "roleList": [
                "家长"
            ]
        },
    ]
}

查询学生列表

接口说明

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

返回参数:

返回样例

{
    "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
        }
    ]
}

查询管理员列表

接口说明

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

返回参数:

返回样例

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

查询教师列表

接口说明

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

返回参数:

返回样例

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

查询家长列表

接口说明

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

返回参数:

返回样例

{
    "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"
            ]
        }
    ]
}

更新用户

查询班级任教信息列表

更新班级任教信息列表

常见问题

附录

签名参数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": 0,
    "msg": "成功",
    "data": [
        {
            "userName": "成绩云",
            "schoolId": 101,
        }
    ]
}

公共返回码

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