在线授课接口定义.md 16.3 KB

Raw Blame History Permalink



返回远程教学之流程消息
返回在线授课相关文档


接口定义


名词定义


在线授课必备消息


在线授课必须的公用群名、群Id（授课指令用）以及聊天室Room的Id（音视频聊天用）


听课学生基本信息
Id、头像、昵称、目标、学习统计（词汇量、阅读量、听力时长、口语时长）
授课教师基本信息
Id，头像，昵称


获取用户访问Qcloud的identifier和签名

/user/me接口中增加返回值：

...
"qcloud": {
    "identifier": "5de6f7a36339ef5bedc3dc8741a1e222",
    "sign": "eJxFkN1ugkAQRt*F2zZ12R8Xe4doG9BGjZLaK4K7g6yUFWElYNN3LxJMb8*ZLzPf-Fi75fYlLgolo9hEpJTWq4Ws5x5DU6gSojgxUHbYZoxhhB62hrJSZ90JjGxmY4LQv1QStFGJ6oNMwjjhMRkTMoGEHUAKIoXDqR3bgDEeMpU6dsMf8y-P38xWp0nwbXahDg*e66U34be6qjd1VmdN6gZzAQ5-aszeXI9*6i7eQK3VjE61TZcB359QkKD3URhePqdbslq3eSBu-LLw89Fjmcyivva9GL1fTgljgzQqh54zh3DGKB94LMT5qk1k2gL6P-3*AfZQX20_"
  },
...


更新鱼卡状态说明


鱼卡状态
状态说明
是否需要客户端参与
备注


创建
鱼卡创建初始状态
N


分配课程
分配课程
N


分配教师
匹配教师
N


等待学生上课应答
老师发起上课邀请后
N


就绪
双方进入房间，学生课程已下载
Y


正在上课
老师点击开始上课
Y


完成
下课（1.点击下课。2.强制下课）
Y
下课前5分钟内离开，服务器自己更新状态


教师旷课
上课5分钟后老师没有发起邀请
N


学生旷课
上课5分钟后学生没有接受邀请
N


学生早退
学生中途离开5分钟以上
Y
客户端老师端上报信息


教师早退
教师中途离开5分钟以上
Y
客户端学生端上报信息


系统异常
异常
Y
客户端双方上报信息


0.统一状态码


设备未绑定成功     错误码：101 描述：设备未绑定成功
deprecate 工单校验失败       错误码：102 描述：工单校验失败

进入房间回调失败   错误码: 103 描述: 进入房间回调失败
工单不存在 错误码: 105 描述: 工单不存在


1.显示学生、课程等信息


说明：授课客户端需要获取在线授课必备消息和听课学生基本信息

显示学生信息，课程信息，饼图，柱状图

is_start参数表示根据服务器时间判断该课程是否可以开始


接口地址：/teaching/student/info

请求方式：GET

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


腾讯云的用户identifier 为盒子鱼用户id的小写md5值

Response：

{
  "data": {
    "student_detail": {
      "student_info": {
        "user_id":12938,
        "real_name": "Mmm",
        "figure_url": "http://avatars.boxfish.cn/user/12938/figure/1423708364.jpg",
        "level": 6,
        "level_name": "滔滔6级"
      },
      "lesson_info": {
        "id": "L3NoYXJlL3N2bi_nvo7lm73or63mlocyLTEvMDAxLkV2ZW5pbmcgYXQgSG9tZS54bHN4",
        "name": "Evening at Home",
        "lastModified": 1448379647022,
        "type": "全面提高",
        "difficulty": "1.5",
        "cover": "73dcb39a42bbfd6b3cc83b2569cf4bce"
      },
      "achievement_info": {
        "read_word_count": "0词",
        "listening_time": "0秒",
        "record_time": "0秒",
        "word_count": "3词"
      },
      "course_type_info": {
        "course_type_ratio": [
          {
            "course_type": "Conversation",
            "ratio": 0.1
          },
          {
            "course_type": "Passage",
            "ratio": 0.05
          },
          {
            "course_type": "Function",
            "ratio": 0.15
          },
          {
            "course_type": "Phonics",
            "ratio": 0.1
          },
          {
            "course_type": "Examination",
            "ratio": 0.1
          },
          {
            "course_type": "Words",
            "ratio": 0.1
          },
          {
            "course_type": "Grammar",
            "ratio": 0.2
          },
          {
            "course_type": "Textbook",
            "ratio": 0.1
          },
          {
            "course_type": "Music",
            "ratio": 0.1
          }
        ],
        "course_count": 324
      }
    },
    "group_room_info": {
      "group_name": "BOXFiSH Online Teaching Group",
      "group_id": "@TGS#2SMUBTAER",
      "chat_room_id": 359755386104019
    },
    "is_start": false,
    "start_time":"2016-06-17 14:00:00",
    "end_time":"2016-06-17 14:30:00"
  },
  "returnCode": 200,
  "returnMsg": "success"
}


1.plus 校验工单状态接口

接口地址：/teaching/fishcard/validate

请求方式：GET

Request Params: 


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


report_time
否
上报时间
2016-07-20 00:00:00


Response:

1.工单有效

{
  "data": {},
  "returnCode": 200,
  "returnMsg": "success"
}


2.工单无效


(1) 未到上课时间

{
  "data": {},
  "returnCode": 10,
  "returnMsg": "未到上课时间"
}


(2) 迟到未在上课时间

{
  "data": {},
  "returnCode": 20,
  "returnMsg": "迟到未在上课时间"
}


(3) 不存在对应的工单

{
  "data": {},
  "returnCode": 1,
  "returnMsg": "不存在对应的工单"
}


2.发推送 - 通知学生开始上课


说明：通知某次课程相应的学生准备上课，通过发送推送信息的方式通知给学生。推送的通知中应该包括在线授课必备消息和授课教师的基本信息


接口地址：/teaching/student/push

请求方式：GET

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


推送json：

{
  "type":"ONCLASS",
  "figure_url": "http://wx.qlogo.cn/mmopen/PiajxSqBRaEJrztQnGAk8X1G2A0AfjvPRBdgLFOjxsM9AoicoOUrH3Yia3qY9uic5ibQO6wMkJ6bPUx15IN4Vrxv8CA/0",
  "teacher_name": "喜洋洋老师",
  "teacher_id": "5",
  "work_order_id": "34",
  "start_time": "2016-05-18 09:00:00",
  "end_time": "2016-05-18 10:00:00",
  "group_name": "boxfish-class001",
  "group_id": "@TGS#2AA4BQAEN",
  "chat_room_id": "100001"
}


Response:

1.工单有效

{
  "data": {
    "msg_id": 3385486500,
    "sendno": 1380240050,
    "originalContent": "{\"sendno\":\"1380240050\",\"msg_id\":\"3385486500\"}",
    "resultOK": true,
    "rateLimitQuota": 600,
    "rateLimitRemaining": 599,
    "rateLimitReset": 60
  },
  "returnCode": 200,
  "returnMsg": "success"
}


2.工单无效

(1) 未到上课时间

{
  "data": {},
  "returnCode": 10,
  "returnMsg": "未到上课时间"
}


(2) 迟到未在上课时间

{
  "data": {},
  "returnCode": 20,
  "returnMsg": "迟到未在上课时间"
}


(3) 不存在对应的工单

{
  "data": {},
  "returnCode": 1,
  "returnMsg": "不存在对应的工单"
}


3.课程正常结束接口


finish_type参数表示课程结束的类型，用户自己结束，传NORMAL; 到时间强制结束传FORCE; 老师提前结束传 "EARLY"


接口地址：/teaching/student/finish

请求方式： POST

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


finish_type
是
结束类型
"FORCE" or "NORMAL" or "EARLY"


report_time
否
上报时间
2016-07-20 00:00:00


返回值：

{
  "data": {},
  "returnCode": 200,
  "returnMsg": "success"
}


4.房间进入状态回调接口


说明：老师进入房间、学生进入房间各回调一次


接口地址：/teaching/callback/chat_room

请求方式：POST

Request body：

{
    "userId":12938,
    "type":"TEACHER",
    "workOrderId": 34,
    "chatRoomId":12345
}


Response


{
  "data": {},
  "returnCode": 200,
  "returnMsg": "success"
}


5.客户端断线重连获取课程状态


说明：


接口地址：/teaching/course/status

请求方式：GET

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


Response：

{
  "data": {
      "recover": true
  },
  "returnCode": 200,
  "returnMsg": "success"
}


6.学生端未收到上课推送主动发起上课接口


说明：


接口地址：/teaching/student/enter_class

请求方式：GET

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


Response:

1.工单有效

{
  "data": {
    "group_id": "@TGS#2SMUBTAER",
    "chat_room_id": 359755386104019
  },
  "returnCode": 200,
  "returnMsg": "success"
}


2.工单无效

(1) 未到上课时间

{
  "data": {},
  "returnCode": 10,
  "returnMsg": "未到上课时间"
}


(2) 迟到未在上课时间

{
  "data": {},
  "returnCode": 20,
  "returnMsg": "迟到未在上课时间"
}


(3) 不存在对应的工单

{
  "data": {},
  "returnCode": 1,
  "returnMsg": "不存在对应的工单"
}


7.获取课程所有资源列表


说明： 学生端调用，从学生端的课程列表可以获取到lesson_id


接口地址：/teaching/resource/lesson

请求方式：GET

Request params：


参数名
是否必须
说明
参数类型


lesson_id
是
课程id
String


Response ：

{
  "data": [
    "0a29673921a26ffb5e5ee81ffed45a9e",
    "0c8a151d1b5eb95bd435e2e1af23ea15",
    "2156d9b3f571381b3eca40d6e9d6e1cc"
    "23dc1178bf9b5f813911f4e798949233",
    ...
    "e77a984dc4cbf889c081f8a53a36f859"
  ],
  "returnCode": 200,
  "returnMsg": "success"
}


8 .旷课回调接口


在Request body的参数中,userId是用户自己的id, type是用户类型, TEACHER 或者STUDENT


接口地址：/teaching/callback/absent

请求方式：POST

Request params：


参数
是否必须
说明
类型


report_time
否
上报时间
2016-07-20 00:00:00


Request body：

{
    "userId":12938,
    "type":"STUDENT",
    "workOrderId":3979
}


Response ：

{
  "data": {},
  "returnCode": 200,
  "returnMsg": "success"
}


9.进入课堂回调接口


老师点击开始上课后调用该接口


接口地址：/teaching/callback/start_class

请求方式：POST

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


report_time
否
上报时间
2016-07-20 00:00:00


Response：

{
  "data": {

  },
  "returnCode": 200,
  "returnMsg": "success"
}


10.取消邀请上课接口


老师在邀请学生上课页面点击取消按钮时调用该接口


接口地址：/teaching/student/cancel_push

请求方式：GET

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


report_time
否
上报时间
2016-07-20 00:00:00


Response:

{
  "data": {

  },
  "returnCode": 200,
  "returnMsg": "success"
}


11.学生进入课堂状态回调接口-学生端调用


status_type参数说明：老师点击立即上课后学生收到推送，学生点击接受后调该接口传ACCEPTED，上课资源准备完成后再次调用该接口，传READY

老师发起上课邀请后，如果学生端收到邀请，没点接受之前，调用该接口，传CONNECTED 参数，表示学生老师已经连通。


接口地址：/teaching/callback/student_status

请求方式：POST

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


status_type
是
状态类型
"ACCEPTED" or "READY" or "RESOURCE_DOWNLOAD_FAIL" or "CONNECTED"


report_time
否
上报时间
2016-07-20 00:00:00


Response：

成功：

{
  "data": {

  },
  "returnCode": 200,
  "returnMsg": "success"
}


失败：

{
  "data": {

  },
  "returnCode": 106,
  "returnMsg": "学生状态回调失败"
}


#12. 上报腾讯云错误码接口

接口地址：/teaching/callback/qcloud/error_info

请求方式：POST

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


error_code
是
错误码
String


error_msg
是
错误信息
String


Response body：

{
  "data": {},
  "returnCode": 200,
  "returnMsg": "success"
}


#13 创建群组接口


使用场景：老师点开始上课时，腾讯云提示错误，比如：10007 没有权限，10010 群组不存在时调用此接口创建新群


接口地址：/teaching/create_group

Request Method：POST

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


Response Body:

创建成功：

{
  "data": "@TGS#2R2DUIBEM",
  "returnCode": 200,
  "returnMsg": "success"
}


工单不存在时：

{
  "data": null,
  "returnCode": 105,
  "returnMsg": "工单不存在"
}


#14 上报学生已在线接口

接口地址：/teaching/callback/student_online

Request Method：POST

Request Body:

{
    "student_id":12938,
    "report_time":"2016-08-03 19:54:10",
    "is_login":true
}


Response Body:


{
  "data": {},
  "returnCode": 200,
  "returnMsg": "success"
}


#15 学生上完课奖励积分接口


奖励规则：

奖励积分根据课程难度分为5档

课程难度为1，在1500-2000之间随机加一个分数；

课程难度为2，2500-3000；

课程难度为3，3500-4000；

课程难度为4，4500-5000；

课程难度为5，5500-6000


接口地址：/teaching/student/score

Request Method：POST

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


Response Body:

{
  "data": {
    "score": 2546
  },
  "returnCode": 200,
  "returnMsg": "success"
}


#16 学生端进入课堂接口


说明： returnCode 除了返回200以外，直接提示returnMsg 即可。


接口地址：/teaching/student/checkin

Request Method：GET

Request params：


参数名
是否必须
说明
参数类型


work_order_id
是
工单id
Long


report_time
否
客户端时间
String


Response Body:

可以进入课堂：

{
    "data": {
        "onclass": true,
        "course_info": {
            "teacherId": 1296861,
            "groupId": "@TGS#2WHIZEBEO",
            "chatRoomId": 212968615
        },
        "course_data": [
            "0a29673921a26ffb5e5ee81ffed45a9e",
            "0c8a151d1b5eb95bd435e2e1af23ea15",
            "2156d9b3f571381b3eca40d6e9d6e1cc",
            "23dc1178bf9b5f813911f4e798949233",
            "e77a984dc4cbf889c081f8a53a36f859"
        ]
    },
    "returnCode": 200,
    "returnMsg": "success"
}


未到上课时间：

{
  "data": {},
  "returnCode": 10,
  "returnMsg": "未到上课时间"
}


不存在对应的鱼卡：

{
  "data": {},
  "returnCode": 1,
  "returnMsg": "不存在对应的工单"
}