电子班牌

为电子班牌设备提供初始化绑定教室,获取教室等信息

设备初始化流程

在初始化界面,需要以下几步:

1. 拉取学校列表

GET /api/v1/schools

Response 200

返回的是学校列表,每个学校的数据结构是:

字段名称 类型 描述
id number 学校ID,需要存储在本地,作为后续请求的x-school-id请求报头
name string 学校名称,最多50个字
url string 学校地址,比如 https://bdfz.seiue.com
district string 所属地址,比如 北京

name显示在列表中供选择。

2. 选择学校并存储

选择学校后,应用需要将学校ID存储在本地(长时间,重新初始化时可销毁)。

然后可以获取学校对应的教室列表,这时的请求header上,需要有x-school-id: 学校ID来分辨哪个学校(注意不是在请求链接上,是header报头方式的)

3. 获取教室列表

接口定义在 教室管理 文档里

4. 将设备绑定教室

选择好教室,点击确认后,需要在服务器端注册绑定关系,方便统计和管理。

POST /api/v1/classroompad/devices
x-school-id: Number

classroom_id=Number&device_id=String

POST发送的字段:

字段名 值类型 描述
classroom_id number 选择的教室ID
device_id string 设备ID字符串,可以是mac地址或者其它唯一ID

设备管理

1. 获取当前设备绑定的教室信息

获取课表都需要教室ID,因此需要先用设备ID换取教室ID

GET /api/v1/classroompad/devices/:device_id
x-school-id: Number

原有的 /api/v1/classroompad/bind?device_id=String 不符合RESTful规范,所以更改了

Parameters

Name Type Description
device_id string 设备ID,和绑定时的一样

Response 200

绑定成功,返回教室详情。

{
    "id": 3725,
    "school_id": 3,
    "type": "classroom",
    "name": "203",
    "created_by": 2016,
    "updated_by": 0,
    "created_at": "2016-11-27 10:11:08",
    "updated_at": "0000-00-00 00:00:00",
    "current_status": "notice",
    "notification": {
        "title": "第3考场",
        "content": "考试内容:英语听力<br/>考试中,请保持安静"
    }
}

客户端需要定时刷新教室状态,建议在5分钟以内。

应该需要定时请求三个接口:

  • 设备的教室详情(本接口)
  • 教室日课表接口(如果教室current_statusnormal
  • 教室通知列表接口(如果教室current_statusnormal

返回的教室详情,用 current_status 来判断班牌应该怎么显示,有以下状态值:

  • normal 正常显示,拉取课表显示今天正在上课。还会同时出现 next_class_time 字段,表示下次有课时间
  • idle 空闲中,还会同时出现 next_class_time 字段,表示下次有课时间
  • notice 教室有重要通知,需要进入通知状态,通常是考试等,会同时有 notification 对象字段:
    • 客户端遇到此状态,不需要显示课表。直接在屏幕中央显示通知标题和内容。
    • notification.title 通知标题,比如 英语第2考场
    • notification.content 通知内容,富文本内容,可能为空
  • blank 黑屏界面,一般是晚上放学后,不需要显示任何内容

Response 404

设备还没有绑定的教室,需要初始化绑定教室

2. 解除当前设备绑定的教室

解除绑定教室的关联,设备重新回到初始化状态

DELETE /api/v1/classroompad/devices/:device_id
x-school-id: Number

原路径 /api/v1/classroompad/bind?device_id=String 已变更

Parameters

Name Type Description
device_id string 设备ID,和绑定时的一样

Response 204

解除绑定成功,不返回任何内容

Response 422

解除绑定失败,可将响应的message显示出来

3. 检查应用更新

可以定期(一天)调用此接口,不用发送 access token 等登录数据。

GET /api/v1/classroompad/check-updates?client_id=xxx

请求的GET查询参数:

Name Type Description
client_id string 客户端APP id号(创建token时发送的)

Response 200

Name Type Description
latest_version string 三节的版本号 a.b.c
download_url string apk下载的链接
change_logs string 更新日志,纯文本,用\n换行,看有没有必要显示
{
    "latest_version": "1.2.3",
    "download_url": "http://localhost:7789/download/classroompad/latest.apk",
    "change_logs": "2017-10-01\\n完善了刷卡速度"
}

results matching ""

    No results matching ""