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

来自成绩云帮助中心
跳转至： 导航、 搜索
（→‎查询教师列表）
 
（未显示4个用户的302个中间版本）
第1行： 第1行：
−
== 前言 ==
+
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">前言</p> ==
  
 
本文档针对需要对接成绩云系统的平台而编写。
 
本文档针对需要对接成绩云系统的平台而编写。
第5行： 第5行：
 
接入成绩云的平台需要先联系知未科技研发，获取2个基本参数：平台ID'''[platform]'''，平台密钥'''[key]'''。这两个参数也可以反过来向知未科技提供。
 
接入成绩云的平台需要先联系知未科技研发，获取2个基本参数：平台ID'''[platform]'''，平台密钥'''[key]'''。这两个参数也可以反过来向知未科技提供。
  
−
然后提供一个接口URL前缀'''[apiBaseUrl]'''，后面所有的接口都基于这个前缀。
+
然后提供一个接口URL前缀'''[apiBaseUrl]'''，后面所有的接口都基于这个前缀。凡是接口URL是https://chengjiyun.com前缀的，说明这个接口由第三方向成绩云发起请求。而如果接口URL前缀是'''[apiBaseUrl]'''，说明接口是由成绩云向第三方发起请求。
  
 
为每一所接入学校向知未提供一个'''[orgId]'''。
 
为每一所接入学校向知未提供一个'''[orgId]'''。
  
−
== 单点登录 ==
+
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">单点登录</p> ==
 
[[文件:login.png]] <br/><br/><br/>
 
[[文件:login.png]] <br/><br/><br/>
−
;单点登录流程说明：<br/>
+
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">单点登录流程说明</p><br/>
 
1. 第三方平台内添加成绩云访问单点登录链接，点击链接访问成绩云。<br/>
 
1. 第三方平台内添加成绩云访问单点登录链接，点击链接访问成绩云。<br/>
 
2. 成绩云接收来自第三方的的访问参数，查询站点信息。（成绩云是分学段建立站点的；如果一个学校包含了小学、初中、高中，那么成绩云中将分别建立小学、初中、高中三个站点。成绩云分学段建立的站点将使用第三方平台给定的学校唯一标识建立站点关联关系）。<br/>
 
2. 成绩云接收来自第三方的的访问参数，查询站点信息。（成绩云是分学段建立站点的；如果一个学校包含了小学、初中、高中，那么成绩云中将分别建立小学、初中、高中三个站点。成绩云分学段建立的站点将使用第三方平台给定的学校唯一标识建立站点关联关系）。<br/>
第17行： 第17行：
 
4. 第三方平台给定的学校包含多个学段，成绩云将会显示选择站点页面。选择站点页面将列举出访问用户可选择的站点。用户选择对应的站点后，则开始验证用户信息。<br/><br/>
 
4. 第三方平台给定的学校包含多个学段，成绩云将会显示选择站点页面。选择站点页面将列举出访问用户可选择的站点。用户选择对应的站点后，则开始验证用户信息。<br/><br/>
  
−
单点登录链接：
+
;<p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">接口说明</p><br/>
−
<pre> [apiBaseUrl]/[paltform]?orgId=[学校ID]&account=[账号]&type=[角色]&timestamp=[当前时间戳]&sign=[加密串]</pre>
+
−
<code>paltform</code>:平台ID<br/>
+
 
请求方法:<code>GET</code><br/>
 
请求方法:<code>GET</code><br/>
 
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 +
PC版登录URL：https://chengjiyun.com/portal/'''[platform]'''?orgId='''[orgId]'''&account='''[account]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
 +
移动版登录URL：https://chengjiyun.com/mobile-portal/'''[platform]'''?orgId='''[orgId]'''&account='''[account]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
 
访问参数：
 
访问参数：
  
 
{| class="wikitable"
 
{| class="wikitable"
−
|+访问参数
 
 
|-
 
|-
 
| style="width:40px; text-align:center;" | 参数
 
| style="width:40px; text-align:center;" | 参数
第44行： 第43行：
 
|type
 
|type
 
|string
 
|string
−
|是
+
|否
−
|角色
+
|学段，可选值为“小学”、“初中”、“高中”。如果存在多学段且不填此字段，系统会让用户选择。
 
|-
 
|-
 
|timestamp
 
|timestamp
 
|int
 
|int
 
|是
 
|是
−
|时间戳time()
+
|时间戳（Unixtime），有效时长7200秒
 
|-
 
|-
 
|sign
 
|sign
 
|string
 
|string
 
|是
 
|是
−
|加密串, 详见附录签名参数sign生成说明
+
|签名, 详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 
|}
 
|}
  
−
== 查询用户 ==
+
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询用户</p> ==
  
−
=== 查询所有用户列表 ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询所有用户列表</p> ===
 +
此接口由成绩云向第三方发起请求，获取用户列表。
  
−
此接口是下面其它接口的超集，后面的接口通过role参数查询子集。
+
成绩云仅需要4种用户角色：学生，教师，管理员，家长。<br/>
−
 
+
此接口是下面其它接口的超集，后面的接口通过role参数查询子集。当指定了role参数后，返回结果中，可忽略用户的角色属性。<br/><br/>
−
=== 查询学生列表 ===
+
  
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST</code>  <br/>
 +
请求URL:'''[apiBaseUrl]'''/queryUsers<br/>
 +
请求参数:<br/>
 
{| class="wikitable"
 
{| class="wikitable"
−
|+请求参数
 
 
|-
 
|-
−
| style="width:60px; text-align:center;" | 参数
+
| style="width:80px; text-align:center;" | 参数
−
| style="width:60px; text-align:center;" | 类型
+
| style="width:150px; text-align:center;" | 类型
−
| style="width:80px; text-align:center;" | 是否必填
+
| style="width:100px; text-align:center;" | 是否必填
−
| style="width:60px; text-align:center;" | 描述
+
| style="width:250px; text-align:center;" | 描述
 
|-
 
|-
 
|orgId
 
|orgId
 
|string
 
|string
 
|是
 
|是
−
|学校id
+
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|否
 +
|角色。可选值为“学生”、“教师”、“管理员、“家长”
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 
|}
 
|}
  
 +
返回参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:40px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:200px; text-align:center;" | 描述
 +
|-
 +
|account
 +
|string
 +
|账号
 +
|-
 +
|name
 +
|string
 +
|姓名
 +
|-
 +
|roleList
 +
|array
 +
|角色数组
 +
|-
 +
|studentId
 +
|string
 +
|学号。要求同一个学校内唯一
 +
|-
 +
|gender
 +
|string
 +
|性别，可选“男”、“女”或“”（空字符串）
 +
|-
 +
|grade
 +
|int
 +
|年级，7表示初一，10表示高一，以此类推。
 +
|-
 +
|class
 +
|string
 +
|班别名称
 +
|}
  
 
'''返回样例'''
 
'''返回样例'''
 
<pre>
 
<pre>
 
{
 
{
−
     "list": [
+
     "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 
         {
 
         {
−
             "id": "zhiwei_01",
+
             "account": "zhiwei_01",
−
             "schoolId": "20190101",
+
             "studentId": "20190101",
 
             "name": "刘备",
 
             "name": "刘备",
−
             "sex": "0",
+
             "gender": "男",
−
             "grade": "10",
+
             "grade": 10,
−
             "class": "1"
+
             "class": "1",
 +
            "roleList": [
 +
                "学生"
 +
            ]
 
         },
 
         },
 
         {
 
         {
−
             "id": "zhiwei_02",
+
             "account": "zhiwei_06",
−
             "schoolId": "20190102",
+
             "name": "单福",
−
             "name": "关羽",
+
             "roleList": [
−
            "sex": "0",
+
                "管理员",
−
            "grade": "11",
+
                "教师"
−
             "class": "2"
+
             ]
 
         },
 
         },
 
         {
 
         {
−
             "id": "zhiwei_03",
+
             "account": "parent_01",
−
            "schoolId": "20190103",
+
             "name": "费曼",
−
             "name": "张飞",
+
             "roleList": [
−
             "sex": "0",
+
                "家长"
−
            "grade": "12",
+
             ]
−
             "class": "3"
+
         },
−
         }
+
 
     ]
 
     ]
 
}
 
}
 
</pre>
 
</pre>
 +
<br/>
  
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询学生列表</p> ===
 +
此接口由成绩云向第三方发起请求，获取学生用户列表。
  
 +
;<p style="font-size:15px;">接口说明</p>
 +
请求方式：<code>POST</code> <br/>
 +
请求URL:  '''[apiBaseUrl]'''/queryUsers<br/>
 +
请求参数：
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:250px; text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|是
 +
|填“学生”
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
返回参数:<br/>
 
{| class="wikitable"
 
{| class="wikitable"
−
|+返回参数
 
 
|-
 
|-
 
| style="width:40px; text-align:center;" | 参数
 
| style="width:40px; text-align:center;" | 参数
−
| style="width:100px; text-align:center;" | 类型
+
| style="width:150px; text-align:center;" | 类型
 
| style="width:300px; text-align:center;" | 描述
 
| style="width:300px; text-align:center;" | 描述
 
|-
 
|-
−
|id
+
|account
 
|string
 
|string
−
|学生在平台内的唯一ID
+
|账号
 
|-
 
|-
−
|schoolId
+
|studentId
 
|string
 
|string
 
|学号。要求同一个学校内唯一
 
|学号。要求同一个学校内唯一
第133行： 第224行：
 
|姓名
 
|姓名
 
|-
 
|-
−
|sex
+
|gender
−
|enum (1, 2)
+
|string
−
|性别。1=>男， 2=>女
+
|性别，可选“男”、“女”或“”（空字符串）
 
|-
 
|-
 
|grade
 
|grade
第142行： 第233行：
 
|-
 
|-
 
|class
 
|class
 +
|string
 +
|班别名称
 +
|}
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "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"
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询管理员列表</p> ===
 +
此接口由成绩云向第三方发起请求，获取管理员用户列表。
 +
;<p style="font-size:15px;">接口说明</p>
 +
请求方式：<code>POST</code>  <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryUsers<br/>
 +
请求参数:
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:250px; text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校 ID
 +
|-
 +
|role
 +
|string
 +
|是
 +
|填“管理员”
 +
|-
 +
|timestamp
 
|int
 
|int
−
|班级。必须为纯整数，不能含有其他字符
+
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 
|}
 
|}
  
−
=== 查询管理员/教师教师列表 ===
+
返回参数:<br/>
 
{| class="wikitable"
 
{| class="wikitable"
−
|+访问参数
 
 
|-
 
|-
 
| style="width:80px; text-align:center;" | 参数
 
| style="width:80px; text-align:center;" | 参数
 
| style="width:100px; text-align:center;" | 类型
 
| style="width:100px; text-align:center;" | 类型
 +
| style="width:150px; text-align:center;" | 描述
 +
|-
 +
|account
 +
|string
 +
|账号
 +
|-
 +
|name
 +
|string
 +
|姓名
 +
|}
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "account": "zhiwei_07",
 +
            "name": "陈大文"
 +
        },
 +
        {
 +
            "account": "zhiwei_08",
 +
            "name": "张伟"
 +
        },
 +
        {
 +
            "account": "zhiwei_09",
 +
            "name": "杨红"
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
<br/>
 +
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询教师列表</p> ===
 +
此接口由成绩云向第三方发起请求，获取教师用户列表。
 +
;<p style="font-size:15px;">接口说明</p>
 +
请求方式：<code>POST</code>  <br/>
 +
请求url: '''[apiBaseUrl]'''/queryUsers<br/>
 +
请求参数:
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 
| style="width:100px; text-align:center;" | 是否必填
 
| style="width:100px; text-align:center;" | 是否必填
−
| style="width:220px; text-align:center;" | 描述
+
| style="width:250px; text-align:center;" | 描述
 
|-
 
|-
 
|orgId
 
|orgId
 
|string
 
|string
 
|是
 
|是
−
|学校的唯一 id
+
|学校 ID
 
|-
 
|-
−
|roleId
+
|role
−
|enum (1, 2)
+
|string
 
|是
 
|是
−
|角色 id。1=>管理员，2=>教师
+
|填“教师”
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 
 +
返回参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:100px; text-align:center;" | 类型
 +
| style="width:150px; text-align:center;" | 描述
 +
|-
 +
|account
 +
|string
 +
|教师的账户
 +
|-
 +
|name
 +
|string
 +
|姓名
 
|}
 
|}
  
第170行： 第398行：
 
<pre>
 
<pre>
 
{
 
{
−
     "list": [
+
     "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 
         {
 
         {
−
             "id": "zhiwei_04",
+
             "account": "zhiwei_04",
 
             "name": "孔明"
 
             "name": "孔明"
 
         },
 
         },
 
         {
 
         {
−
             "id": "zhiwei_05",
+
             "account": "zhiwei_05",
 
             "name": "郭嘉"
 
             "name": "郭嘉"
 
         },
 
         },
 
         {
 
         {
−
             "id": "zhiwei_06",
+
             "account": "zhiwei_06",
 
             "name": "单福"
 
             "name": "单福"
 
         }
 
         }
第187行： 第417行：
 
</pre>
 
</pre>
  
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询家长列表</p> ===
 +
此接口由成绩云向第三方发起请求，获取家长用户列表。
 +
;<p style="font-size:15px;">接口说明</p>
 +
请求方式：<code>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryUsers<br/>
 +
请求参数:
 
{| class="wikitable"
 
{| class="wikitable"
−
|+返回参数
 
 
|-
 
|-
 
| style="width:80px; text-align:center;" | 参数
 
| style="width:80px; text-align:center;" | 参数
−
| style="width:100px; text-align:center;" | 类型
+
| style="width:150px; text-align:center;" | 类型
−
| style="width:180px; text-align:center;" | 描述
+
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:250px; text-align:center;" | 描述
 
|-
 
|-
−
|id
+
|orgId
 
|string
 
|string
−
|平台内的唯一 id
+
|是
 +
|学校 ID
 
|-
 
|-
−
|name
+
|role
 
|string
 
|string
−
|姓名
+
|是
 +
|填“家长”
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 
|}
 
|}
  
−
=== 查询家长列表 ===
+
返回参数:<br/>
 
{| class="wikitable"
 
{| class="wikitable"
−
|+访问参数
 
 
|-
 
|-
−
| style="width:40px; text-align:center;" | 参数
+
| style="width:140px; text-align:center;" | 参数
 
| style="width:100px; text-align:center;" | 类型
 
| style="width:100px; text-align:center;" | 类型
−
| style="width:100px; text-align:center;" | 是否必填
 
 
| style="width:180px; text-align:center;" | 描述
 
| style="width:180px; text-align:center;" | 描述
 
|-
 
|-
−
|orgId
+
|account
 
|string
 
|string
−
|是
+
|账号
−
|学校的唯一 id
+
|-
 +
|name
 +
|string
 +
|姓名
 +
|-
 +
|studentList
 +
|array
 +
|家长关联的学生 ID数组
 
|}
 
|}
−
 
  
  
第223行： 第475行：
 
<pre>
 
<pre>
 
{
 
{
−
     "list": [
+
     "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 
         {
 
         {
−
             "id": "parent_01",
+
             "account": "parent_01",
 +
            "name": "费曼",
 
             "studentList": [
 
             "studentList": [
 
                 "stu_01"
 
                 "stu_01"
第231行： 第486行：
 
         },
 
         },
 
         {
 
         {
−
             "id": "parent_02",
+
             "account": "parent_02",
 +
            "name": "图灵",
 
             "studentList": [
 
             "studentList": [
 
                 "stu_02",
 
                 "stu_02",
第238行： 第494行：
 
         },
 
         },
 
         {
 
         {
−
             "id": "parent_03",
+
             "account": "parent_03",
 +
            "name": "香侬",
 
             "studentList": [
 
             "studentList": [
 
                 "stu_04",
 
                 "stu_04",
第249行： 第506行：
 
</pre>
 
</pre>
  
 +
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">管理用户</p> ==
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">新增用户</p> ===
 +
第三方平台新增用户信息后，主动推送新增的用户到成绩云，通知成绩云新增相应用户。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST（Content-Type:application/json）</code>  <br/>
 +
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 +
请求url: https://chengjiyun.com/vendor-api/addUser?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
 +
URL参数说明（并非所有角色都支持全部参数）:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|platform
 +
|string
 +
|是
 +
|平台ID
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
  
 +
POST数据结构参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:350px; text-align:center;" | 描述
 +
|-
 +
|account
 +
|string
 +
|是
 +
|账号
 +
|-
 +
|roleList
 +
|array
 +
|是
 +
|角色（支持管理员、教师、学生）
 +
|-
 +
|name
 +
|string
 +
|是
 +
|姓名
 +
|-
 +
|studentId
 +
|string
 +
|否
 +
|学号。要求同一个学校内唯一
 +
|-
 +
|gender
 +
|string
 +
|否
 +
|性别，可选“男”、“女”或“”（空字符串）
 +
|-
 +
|grade
 +
|int
 +
|否
 +
|年级，7表示初一，10表示高一，以此类推。
 +
|-
 +
|class
 +
|string
 +
|否
 +
|班别名称
 +
|}
 +
 +
'''请求样例'''
 +
 +
POST数据如下：
 +
<pre>
 +
    [
 +
        {
 +
            "account": "zhiwei_01",
 +
            "name": "刘备",
 +
            "class": "2",
 +
            "roleList": [
 +
                "管理员",
 +
                "教师",
 +
            ]
 +
        },
 +
        {
 +
            "account": "zhiwei_06",
 +
            "name": "单福",
 +
            "gender": "男",
 +
            "roleList": [
 +
                "教师",
 +
            ]
 +
        },
 +
        {
 +
            "account": "student_01",
 +
            "name": "费曼",
 +
            "grade": 7,
 +
            "class": "1",
 +
            "roleList": [
 +
                "教师",
 +
            ]
 +
        }
 +
    ]
 +
</pre>
 +
<br/>
 +
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
}
 +
</pre>
 +
<br/>
 +
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">删除用户</p> ===
 +
第三方平台删除用户信息后，主动推送删除的用户到成绩云，通知成绩云进行删除。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST（Content-Type:application/json）</code>  <br/>
 +
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 +
请求url: https://chengjiyun.com/vendor-api/deleteUser?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
 +
URL参数说明:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|platform
 +
|string
 +
|是
 +
|平台ID
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
POST数据结构参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:350px; text-align:center;" | 描述
 +
|-
 +
|account
 +
|string
 +
|是
 +
|账号
 +
|}
 +
 +
'''请求样例'''
 +
 +
POST数据如下：
 +
<pre>
 +
  [
 +
      "zhiwei_01",
 +
      "zhiwei_06",
 +
      "parent_01"
 +
  ]
 +
</pre>
 +
<br/>
 +
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
}
 +
</pre>
 +
<br/>
 +
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">更新用户</p> ===
 +
第三方平台修改用户信息后，主动推送被修改用户到成绩云进行修改。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST（Content-Type:application/json）</code>  <br/>
 +
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 +
请求url: https://chengjiyun.com/vendor-api/updateUser?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
 +
URL参数说明:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|platform
 +
|string
 +
|是
 +
|平台ID
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
POST数据结构参数（并非所有角色都支持全部参数的修改，例如班别信息对家长角色是无效的）:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:350px; text-align:center;" | 描述
 +
|-
 +
|account
 +
|string
 +
|是
 +
|账号
 +
|-
 +
|name
 +
|string
 +
|否
 +
|姓名
 +
|-
 +
|studentId
 +
|string
 +
|否
 +
|学号。要求同一个学校内唯一
 +
|-
 +
|gender
 +
|string
 +
|否
 +
|性别，可选“男”、“女”或“”（空字符串）
 +
|-
 +
|grade
 +
|int
 +
|否
 +
|年级，7表示初一，10表示高一，以此类推。
 +
|-
 +
|class
 +
|string
 +
|否
 +
|班别名称
 +
|-
 +
|status
 +
|int
 +
|否
 +
|账号状态。可不携带该属性，代表不更新用户状态；若携带该属性，0代表禁用状态，1代表活跃状态。
 +
|-
 +
|}
 +
 +
'''请求样例'''
 +
 +
POST数据如下：
 +
<pre>
 +
    [
 +
        {
 +
            "account": "zhiwei_01",
 +
            "name": "刘备",
 +
            "class": "2",
 +
            "status": 1
 +
        },
 +
        {
 +
            "account": "zhiwei_06",
 +
            "name": "单福",
 +
            "gender": "男",
 +
            "status": 0
 +
        },
 +
        {
 +
            "account": "parent_01",
 +
            "name": "费曼"
 +
        },
 +
    ]
 +
</pre>
 +
<br/>
 +
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
}
 +
</pre>
 +
<br/>
 +
 +
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询班级任教信息列表</p> ==
 +
成绩云向第三方平台发起请求，查询班级任教信息。
 +
<p style="font-size:15px;">'''接口说明'''</p>
 +
请求方式：<code>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryClassStatus<br/>
 +
'''请求参数'''：
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:250px; text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校 ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
'''返回参数''':<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:30px; text-align:center;" | 参数
 +
| style="width:40px; text-align:center;" | 类型
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|year
 +
|int
 +
|入学年份
 +
|-
 +
|grade
 +
|int
 +
|年级
 +
|-
 +
|class
 +
|string
 +
|班别名称
 +
|-
 +
|headTeacher
 +
|string
 +
|班主任的账户 ID
 +
|-
 +
|courseTeacherList
 +
|object
 +
|科目任教信息. 以科目的中文名为属性名, 教师的账户 ID 为 属性值的结构对象
 +
例如：
 +
<pre>
 +
{
 +
"语文":"zhiwei_04",
 +
"数学":"zhiwei_05",
 +
"英语":"zhiwei_06"
 +
}
 +
</pre>
 +
|}
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "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"
 +
            }
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">通知更新班级任教信息列表</p> ==
 +
第三方平台修改班级任教相关的数据后，需要主动通知成绩云重新读取第三方平台的数据更新。此接口无需传入更新的数据，只需通知成绩云即可。
 +
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>GET</code>  <br/>
 +
接口方向:<code>第三方</code>→<code>成绩云</code><br/>
 +
请求URL: https://chengjiyun.com/vendor-api/updateClassStatus?platform='''[platform]'''&orgId='''[orgId]'''&timestamp='''[timestamp]'''&sign='''[sign]'''<br/>
 +
URL参数说明:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:150px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|platform
 +
|string
 +
|是
 +
|平台ID
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名，只对orgId和timestamp签名，不用对POST数据内容签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">查询考试成绩</p> ==
 +
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询考试列表</p> ===
 +
成绩云向第三方平台发起请求，获取考试列表。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST</code>  <br/>
 +
请求URL:  '''[apiBaseUrl]'''/queryExam<br/>
 +
返回格式：<code>Content-Type:application/json</code><br/>
 +
请求参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="text-align:center;" | 参数
 +
| style="text-align:center;" | 类型
 +
| style="text-align:center;" | 是否必填
 +
| style="text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
返回参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:140px; text-align:center;" | 参数
 +
| style="width:100px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|examId
 +
|string
 +
|是
 +
|考试ID
 +
|-
 +
|title
 +
|string
 +
|是
 +
|考试标题
 +
|-
 +
|grade
 +
|int
 +
|是
 +
|年级(可取值1,2,3,4,5,6,7,8,9,10,11,12)
 +
|}
 +
 +
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "examId": "233",
 +
            "title": "考试标题",
 +
            "grade": 11 // 年级值11表示高二
 +
        },
 +
        {
 +
            "examId": "234",
 +
            "title": "考试标题",
 +
            "grade": 12 // 年级值12表示高三
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试总分成绩</p> ===
 +
成绩云向第三方平台发起请求，获取单次考试详细成绩数据。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST</code>  <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryExamDetail<br/>
 +
返回格式：<code>Content-Type:application/json</code><br/>
 +
请求参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="text-align:center;" | 参数
 +
| style="text-align:center;" | 类型
 +
| style="text-align:center;" | 是否必填
 +
| style="text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|examId
 +
|string
 +
|是
 +
|考试ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 +
返回参数:<br/>
 
{| class="wikitable"
 
{| class="wikitable"
−
|+返回参数
 
 
|-
 
|-
 
| style="width:140px; text-align:center;" | 参数
 
| style="width:140px; text-align:center;" | 参数
第257行： 第1,069行：
 
| style="width:180px; text-align:center;" | 描述
 
| style="width:180px; text-align:center;" | 描述
 
|-
 
|-
−
|id
+
|studentId
 
|string
 
|string
−
|家长在平台内的唯一 id
+
|学生学号
 
|-
 
|-
−
|studentList
+
|scores
 
|array
 
|array
−
|家长关联的学生 id数组
+
|科目成绩
 
|}
 
|}
  
−
=== 查询管理员列表 ===
 
  
−
== 更新用户 ==
+
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data": [
 +
        {
 +
            "studentId": "20180101",
 +
            "scores": {
 +
                "语文": 120,
 +
                "数学": 118,
 +
                "英语": 121,
 +
                "物理": 89,
 +
                "化学": 78,
 +
                "生物": 88,
 +
                "政治": 78,
 +
                "历史": 85,
 +
                "地理": 83
 +
            }
 +
        },
 +
        {
 +
            "studentId": "20180102",
 +
            "scores": {
 +
                "语文": 118,
 +
                "数学": 136,
 +
                "英语": 98
 +
            }
 +
        }
 +
    ]
 +
}
 +
</pre>
  
−
== 查询班级任教信息列表 ==
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试小题分科目列表</p> ===
 +
成绩云向第三方平台发起请求，获取考试小题分列表。
 +
;<span style="font-size:15px;">接口说明</span>
 +
请求方式：<code>POST</code>  <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryQuestionList<br/>
 +
返回格式：<code>Content-Type:application/json</code><br/>
 +
请求参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:50px; text-align:center;" | 类型
 +
| style="width:50px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校ID
 +
|-
 +
|examId
 +
|string
 +
|是
 +
|考试ID
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime），有效时长600秒
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
  
−
== 更新班级任教信息列表 ==
+
返回参数:<br/>
 +
{| class="wikitable"
 +
|-
 +
| style="width:140px; text-align:center;" | 参数
 +
| style="width:100px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否允许为 null
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|examId
 +
|string
 +
|否
 +
|考试ID
 +
|-
 +
|courses
 +
|array
 +
|否
 +
|有分析小题分的科目集合
 +
|}
  
−
== 常见问题 ==
 
  
−
== 附录 ==
+
'''返回样例'''
 +
<pre>
 +
{
 +
    "code": 0,
 +
    "msg": "成功",
 +
    "data":
 +
        {
 +
            "examId": "233",
 +
            "courses": [
 +
              "语文",
 +
              "数学",
 +
            ],
 +
        }
 +
}
 +
</pre>
  
−
=== 签名参数sign生成说明 ===
+
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试小题分试卷结构</p> ===
 +
成绩云向第三方平台发起请求，获取单次考试某一科目小题分试卷结构。
 +
<p style="font-size:15px;">'''接口说明'''</p>
 +
请求方式：<code>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryQuestionStructure<br/>
 +
'''请求参数'''：
 +
{| class="wikitable"
 +
|-
 +
| style="width:80px; text-align:center;" | 参数
 +
| style="width:100px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:250px; text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校 ID
 +
|-
 +
|examId
 +
|string
 +
|是
 +
|考试 ID
 +
|-
 +
|course
 +
|string
 +
|是
 +
|科目的中文名
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 
 +
'''返回参数''':<br/>
 +
下面参数的具体定义，请阅读理解  [https://chengjiyun.com/wiki/index.php?title=%E8%AF%95%E5%8D%B7%E7%BB%93%E6%9E%84 试卷结构 ]
 +
{| class="wikitable"
 +
|-
 +
| style="width:30px; text-align:center;" | 参数
 +
| style="width:200px; text-align:center;" | 类型
 +
| style="width:120px; text-align:center;" | 是否允许为 null
 +
| style="width:100px; text-align:center;" | 描述
 +
|-
 +
|number
 +
|string
 +
|否
 +
|题号
 +
|-
 +
|answerType
 +
|enum("主观题"，"客观题")
 +
|否
 +
|类型
 +
|-
 +
|score
 +
|float
 +
|否
 +
|满分值
 +
|-
 +
|scroll
 +
|enum("一卷"，"二卷")
 +
|否
 +
|卷别
 +
|-
 +
|group
 +
|string
 +
|是
 +
| 选做题分组
 +
|-
 +
|questionType
 +
|string
 +
|是
 +
|题型
 +
|-
 +
|knowledge
 +
|string
 +
|是
 +
|知识点
 +
|-
 +
|ability
 +
|string
 +
|是
 +
|能力
 +
|}
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "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
 +
        }
 +
    ]
 +
}
 +
 
 +
</pre>
 +
 
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">查询单次考试小题分成绩</p> ===
 +
成绩云向第三方平台发起请求，获取单次考试某一科目小题分所有学生分数。
 +
<p style="font-size:15px;">'''接口说明'''</p>
 +
请求方式：<code>POST</code> <br/>
 +
请求url:  '''[apiBaseUrl]'''/queryQuestionScore<br/>
 +
'''请求参数'''：
 +
{| class="wikitable"
 +
|-
 +
| style="width:100px; text-align:center;" | 参数
 +
| style="width:100px; text-align:center;" | 类型
 +
| style="width:100px; text-align:center;" | 是否必填
 +
| style="width:300px; text-align:center;" | 描述
 +
|-
 +
|orgId
 +
|string
 +
|是
 +
|学校 ID
 +
|-
 +
|examId
 +
|string
 +
|是
 +
|考试 ID
 +
|-
 +
|course
 +
|string
 +
|是
 +
|科目的中文名
 +
|-
 +
|timestamp
 +
|int
 +
|是
 +
|时间戳（Unixtime）
 +
|-
 +
|sign
 +
|string
 +
|是
 +
|签名。详见附录[https://chengjiyun.com/wiki/index.php?title=%E6%88%90%E7%BB%A9%E4%BA%91%E6%8E%A5%E5%8F%A3%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3#.E7.AD.BE.E5.90.8D.E5.8F.82.E6.95.B0sign.E7.94.9F.E6.88.90.E8.AF.B4.E6.98.8E 签名参数sign生成说明]
 +
|}
 +
 
 +
'''返回参数''':<br/>
 +
下面参数的具体定义，请阅读理解  [https://chengjiyun.com/wiki/index.php?title=%E8%AF%95%E5%8D%B7%E7%BB%93%E6%9E%84 试卷结构 ]
 +
{| class="wikitable"
 +
|-
 +
| style="width:100px; text-align:center;" | 参数
 +
| style="width:100px; text-align:center;" | 类型
 +
| style="width:120px; text-align:center;" | 是否允许为 null
 +
| style="width:280px; text-align:center;" | 描述
 +
|-
 +
|studentId
 +
|string
 +
|否
 +
|学生学号
 +
|-
 +
|scores
 +
|hash
 +
|是
 +
|题号: 分数。分数为 null 时, 表示学生缺答
 +
|}
 +
 
 +
'''返回样例'''
 +
<pre>
 +
{
 +
    "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
 +
            }
 +
        }
 +
    ]
 +
}
 +
 
 +
 
 +
</pre>
 +
 
 +
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">常见问题</p> ==
 +
 
 +
== <p style="background:#6a9ee4;padding:8px 12px;color:#ffffff;">附录</p> ==
 +
 
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">签名参数sign生成说明</p> ===
 
<code>第一步：</code>对传入的参数按照键名排序<br/>
 
<code>第一步：</code>对传入的参数按照键名排序<br/>
 
<code>第二步：</code>使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA <br/>
 
<code>第二步：</code>使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA <br/>
 
<code>第三步：</code>在stringA最后拼接上“&key=[平台密钥]”得到stringSignTemp字符串，并对stringSignTemp进行MD5运算<br/>
 
<code>第三步：</code>在stringA最后拼接上“&key=[平台密钥]”得到stringSignTemp字符串，并对stringSignTemp进行MD5运算<br/>
 
<code>第四步：</code>得到最终请求字符串sign<br/>
 
<code>第四步：</code>得到最终请求字符串sign<br/>
−
<br/>PHP签名算法示例：<br/>
+
<br/><code>PHP签名算法示例:</code><br/>
 
<pre>
 
<pre>
 
//$key 平台密钥
 
//$key 平台密钥
第294行： 第1,411行：
  
 
$data = array(
 
$data = array(
−
   'orgId'=> 2345,
+
   'orgId'=>'testapi',
−
   'account'=> 4567,
+
   'account'=> 'zhiwei_01',
−
   'type'=> 1,
+
   'type'=> '高中',
 
   'timestamp'  => time(),
 
   'timestamp'  => time(),
 
);
 
);
 
$sign = sign($data, $key);
 
$sign = sign($data, $key);
 
</pre>
 
</pre>
 +
 +
注意：一般接口会有一个timestamp参数，如无特别说明，timestamp的有效时间为600秒（登录接口有效时常为7200秒），超过该时长请求无效，以降低受到重放攻击的风险。此时长在实际使用中可能会做出调整，请尽可能地使用实时时间。
  
 
----
 
----
−
=== 返回结果 ===
+
 
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">返回结果</p> ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
第326行： 第1,446行：
 
<pre>
 
<pre>
 
{
 
{
−
     "code": "10000",
+
     "code": 0,
 
     "msg": "成功",
 
     "msg": "成功",
 
     "data": [
 
     "data": [
 
         {
 
         {
 
             "userName": "成绩云",
 
             "userName": "成绩云",
−
             "schoolId": 101,
+
             "studentId": 101,
 
         }
 
         }
 
     ]
 
     ]
第338行： 第1,458行：
  
 
----
 
----
−
=== 公共返回码 ===
+
 
 +
=== <p style="background:#999a9c;padding:8px 12px;color:#ffffff;display:inline-block;">公共返回码</p>  ===
 
开发者每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返回码信息调试接口，排查错误。
 
开发者每次调用接口时，可能获得正确或错误的返回码，开发者可以根据返回码信息调试接口，排查错误。
 
返回码如下:
 
返回码如下:
第347行： 第1,468行：
 
| style="width:200px; text-align:center;" | 消息(msg)
 
| style="width:200px; text-align:center;" | 消息(msg)
 
|-
 
|-
−
|10000
+
|0
 
|成功
 
|成功
 
|-
 
|-

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

前言

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

接入成绩云的平台需要先联系知未科技研发，获取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参数后，返回结果中，可忽略用户的角色属性。

接口说明

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

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

返回参数:

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

返回样例 

{
    "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
请求参数：

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

返回参数:

参数 类型 描述
account string 账号
studentId string 学号。要求同一个学校内唯一
name string 姓名
gender string 性别，可选“男”、“女”或“”（空字符串）
grade int 年级
class string 班别名称

返回样例 

{
    "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
请求参数:

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

返回参数:

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

返回样例 

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


查询教师列表

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

接口说明

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

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

返回参数:

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


返回样例 

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

查询家长列表

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

接口说明

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

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

返回参数:

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


返回样例 

{
    "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参数说明（并非所有角色都支持全部参数）:

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

POST数据结构参数:

参数 类型 是否必填 描述
account string 是 账号
roleList array 是 角色（支持管理员、教师、学生）
name string 是 姓名
studentId string 否 学号。要求同一个学校内唯一
gender string 否 性别，可选“男”、“女”或“”（空字符串）
grade int 否 年级，7表示初一，10表示高一，以此类推。
class string 否 班别名称

请求样例

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参数说明:

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

POST数据结构参数:

参数 类型 是否必填 描述
account string 是 账号

请求样例

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参数说明:

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

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

参数 类型 是否必填 描述
account string 是 账号
name string 否 姓名
studentId string 否 学号。要求同一个学校内唯一
gender string 否 性别，可选“男”、“女”或“”（空字符串）
grade int 否 年级，7表示初一，10表示高一，以此类推。
class string 否 班别名称
status int 否 账号状态。可不携带该属性，代表不更新用户状态；若携带该属性，0代表禁用状态，1代表活跃状态。

请求样例

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
请求参数：

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

返回参数:

参数 类型 描述
year int 入学年份
grade int 年级
class string 班别名称
headTeacher string 班主任的账户 ID
courseTeacherList object 科目任教信息. 以科目的中文名为属性名, 教师的账户 ID 为 属性值的结构对象

例如： 

{
 "语文":"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参数说明:

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

查询考试成绩

查询考试列表

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

接口说明

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

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

返回参数:

参数 类型 是否必填 描述
examId string 是 考试ID
title string 是 考试标题
grade int 是 年级(可取值1,2,3,4,5,6,7,8,9,10,11,12)


返回样例 

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

查询单次考试总分成绩

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

接口说明

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

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

返回参数:

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


返回样例 

{
    "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
请求参数:

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

返回参数:

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


返回样例 

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

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

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

接口说明

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

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

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

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

返回样例 

{
    "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
请求参数：

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

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

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

返回样例 

{
    "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 int 公共返回码，详见附录公共返回码
msg string 返回信息
data object 返回的查询或操作数据,数据可能是对象或数组。具体根据每个API而定。

返回示例： 

{
    "code": 0,
    "msg": "成功",
    "data": [
        {
            "userName": "成绩云",
            "studentId": 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=1991”