跳转至

扫读笔_学习园地功能说明文档

文档状态

文件标识： TuringOS-textbook-V1.2.1
系统版本： API
完成日期： 2021年2月1日

文档修订记录

为便于后续文档维护，文档版本号将由三部分组成，第一个数字为主版本号，第二个数字为功能版本号，第三个数字为修订版本号：

文档版本号 修订日期 修订原因
V1.2.1 2022.02.11 创建文档

一、功能简介

学习园地可通过教材设置接口获取小学语文和英语常用教材信息，并对教材音频进行播放。

目前该功能主要通过三个部分实现，分别为设置教材信息、获取教材音频、使用云端播放器播放音频：

1.设置教材

主要通过教材的三个坐标属性定位到唯一教材，即：教材类别、年级上下册、教材版本。

教材坐标属性：

教材属性 可选内容
教材类别 [“语文”, “英语”]
年级 [“一年级上册”, “一年级下册”, “二年级上册”, ……]
教材版本 [“部编版”, “人教版”, “沪教版”, ……]

2.获取教材音频

通过定位教材信息，获取教材内的单元及课程音频列表。在语文和英语教材中，存在两种结构：

  • 一种只包含课程，即一层结构；
  • 一种包含单元和课程，即两层结构。

img

为便于快速定位信息列表，针对使用情况提供了以下几种输出方式：

  • 当教材为一层结构时，输出“课程”层级列表，可参考2.1.1
  • 当教材为两层结构时，输出“单元”层级列表，可参考2.1.2
  • 当教材为两层结构时，直接输出“课程”层级列表，可参考2.2.3
  • 当教材为两层结构时，指定某个单元下的“课程”层级列表，可参考2.1.4

3.云端播放器

针对RTOS相关设备，由于开发周期大、本地资源少等特点，为提高最终产品质量及方案落地，图灵在对音频播放器的实现方面，采用了云端播放器的实现方式。将云端和控制逻辑放在云端，仅提供控制面板API，用于硬件端对接。

云端播放器控制面板说明

  • 绿色部分为内容显示，例如：专辑名称显示，音频名称显示。

  • 黄色部分为控制面板API，操作播放器：

  • 上一首/下一首，基于当前播放列表，进行上一首/下一首操作

  • 播放/暂停，云端暂不提供断点续播

  • 单曲循环/专辑循环，由于云端url有时效性，在单曲循环时，重新拉取url

云端播放器

二、接口要求

1.加密说明

为了保证接口的安全性和稳定性，需要对接口数据进行加密：

  1. 上传字段中必须包含的信息：APIKey，Secret
  2. 对于上传参数，需要统一按照加密方式处理，最终请求输入如下所示：
参数 说明 备注
加密模式 CBC -
填充 PKCS5Padding -
数据块 128位（密钥为16位） -
密码 secretKey Secret，图灵官网申请
偏移量 secretKey Secret，图灵官网申请
输出 base64 -
字符集 utf-8 -

2.接口说明

2.1 请求方法

正式环境域名：http://stat.turingos.cn

2.2 通用请求示例

加密后请求示例：

{
    "key": "ed474dae62*********67a1788",
    "timestamp": "150******7793",
    "service_identify": "scanPen",
    "data": "加密后的内容"
}

请求参数说明

参数 类型 是否必须 描述
key String Y 图灵biz平台申请的Apikey
timestamp String Y 当前时间戳
data String Y 请求内容，需填写加密后的结果
service_identify String Y 场景模式
scanPen为扫读笔场景

2.3 通用返回示例

{
    "code": 200,
    "message": "success",
    "data": "xxx"
}

返回参数说明

参数 类型 是否必须 描述
code Integer Y 状态码，200为成功，其他code参考异常错的说明
message String Y 返回信息
data List Y 请求成功列表

三、接入流程

1.教材设置

1.1 获取教材信息

该接口可通过教材类别（英语或语文），依次获取对应教材版本、年级上下册目录结构，使设备端能在页面中逐步引导用户选择教材维度，帮用户快速定位到具体书本信息；

  • Method: POST
  • Content-Type: application/json
  • Path：/textBook/textBookSetting

1.1.1 用类别获取版本、年级

请求示例

data加密前内容：

 {
   "deviceId":"ai000000000003",
   "subject":1
 }

请求参数说明

参数名 类型 是否必须 说明
deviceId string Y 设备号
subject int Y 教材类别
0为语文
1为英语

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "textSettingInit": [
            {
                "grade": "一年级上册",
                "version": [
                    "人教版（一起）",
                    "外研社版（一起）"
                ]
            },
            {
                "grade": "一年级下册",
                "version": [
                    "泽林版（一起）",
                    "人教版（一起）"
                ]
            },
            {
                "grade": "二年级上册",
                "version": [
                    "泽林版（一起）",
                    "人教版（一起）",
                    "外研社版（一起）"
                ]
            },
            {
                "grade": "二年级下册",
                "version": [
                    "泽林版（一起）",
                    "人教版（一起）"
                ]
            },
            {
                "grade": "三年级上册",
                "version": [
                    "人教PEP版（三年级起点）",
                    "泽林版（三起）",
                    "人教版（一起）"
                ]
            },
            {
                "grade": "三年级下册",
                "version": [
                    "泽林版（三起）",
                    "人教版（一起）",
                    "人教PEP版（三起）"
                ]
            }
        ]
    }
}

返回参数说明

参数名 类型 是否必须 说明
textSettingInit arrary Y 教材信息列表

textSettingInit字段说明

参数名 类型 是否必须 说明
grade string Y 年级上下册
version arrary Y 教材版本

1.1.2 用类别、年级获取版本

请求示例

data加密前内容：

 {
   "deviceId":"ai000000000003",
   "subject":1,
   "gradeName":"三年级下册"
 }

请求参数说明

参数名 类型 是否必须 说明
deviceId string Y 设备号
subject int Y 教材类别
0为语文
1为英语
gradeName string Y 年级上下册

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "versionList": [
            "泽林版（三起）",
            "人教版（一起）",
            "人教PEP版（三起）",
            "人教精通版（三起）",
            "外研社版（一起）",
            "山东科学技术版（三起）",
            "湖南山东教育版（三起）",
            "四川教育版（三起）",
            "沪教版（口语交际）",
            "辽师大版（三起）",
            "辽师大版（一起）",
            "河北教育版（一起）",
            "河北教育版（三起）"
        ]
    }
}

返回参数说明

参数名 类型 是否必须 说明
versionList arrary Y 教材版本列表

1.1.3 用类别、年级、版本获取教材信息

请求示例

data加密前内容：

 {
   "deviceId":"ai000000000003",
   "subject":1,
   "gradeName":"三年级下册",
   "versionName":"人教PEP版（三起）"
 }

请求参数说明

参数名 类型 是否必须 说明
deviceId string Y 已上传至设备列表且成功激活的设备号
subject int Y 教材类别
0为语文
1为英语
gradeName string Y 年级上下册
versionName string Y 教材版本

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "textBook": [
            {
                "gradeName": "三年级下册",
                "subject": "英语",
                "bookName": "人教PEP版（三起）英语三年级下册",
                "version": "人教PEP版（三起）",
                "bookId": "4a9728e3090246b7b0307d72a1a644f2"
            }
        ]
    }
}

返回参数说明

参数名 类型 是否必须 说明
textBook arrary Y 教材信息

textBook字段说明

参数名 类型 是否必须 说明
bookId string Y 教材唯一标识（同booksign），用于保存、查询教材信息
bookName string Y 教材名称
subject string Y 教材类别
gradeName string Y 教材年级
version string Y 教材版本

1.2 保存教材设置

获取到“教材目录结构”后，可通过该接口，将已选择的教材信息保存至云端，以便客户通过语音助手进行点播或直接选择该教材下的单元、课程；

  • Method: POST
  • Content-Type: application/json
  • Path：/textBook/saveTextBookSetting

请求示例

data加密前内容：

{
   "deviceId":"ai000000000003",
   "bookId":"fdfsdaewedsdfsdfs"
}

请求参数说明

参数 类型 是否必须 描述
deviceId String Y 已上传至设备列表且成功激活的设备号
bookId string Y 教材唯一标识

返回示例

{
    "code": 200,
    "message": "success",
    "data": null
}

1.3 获取设置过的教材信息

通过“保存教材设置”接口，将教材信息保存至云端后，可使用该接口拉取云端最新保存的教材信息，以便在设备端显示教材；

  • Method: POST
  • Content-Type: application/json
  • Path：/textBook/getTextBookSettingList

请求示例

data加密前内容：

{
   "deviceId":"ai000000000003"
}

请求参数说明

参数 类型 是否必须 描述
deviceId string Y 已上传至设备列表且成功激活的设备号

返回示例

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "subject": "英语",
            "grade": "三年级",
            "term": "下册",
            "bookName": "人教版（一起）英语三年级下册",
            "version": "人教版（一起）",
            "bookId": "1d5e050299584ad5952ddb2eea054e3e"
        }
    ]
}

返回参数说明

参数 类型 是否必须 描述
subject string Y 教材类别
grade string Y 教材年级
term string Y 教材上下册
bookName string Y 教材名称
version string Y 教材版本
bookId string Y 教材唯一标识

2.获取教材音频

2.1 获取教材单元或课程信息列表

  • Method: POST
  • Content-Type: application/json
  • Path：/textBook/itemList

2.1.1 一层结构，输出课程

当教材为一层结构时，在请求参数中输入教材唯一标识（bookId），直接输出课程ID及名称（如：人教为一层结构，返回所有“class”层级的信息列表，无unit层级）

请求示例

data加密前内容：
{
    "bookId": "4a9728e3090246b7b0307d72a1a644f2",
    "deviceId":"ai000000000003"
}

请求参数说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
deviceId string Y 已上传至设备列表且成功激活的设备号

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "level": "class",
        "list": [
            {
                "classId": 5698,
                "unitId": 0,
                "className": "1Welcome back to school"
            },
            {
                "classId": 5699,
                "unitId": 0,
                "className": "2My family"
            },
            {
                "classId": 5700,
                "unitId": 0,
                "className": "3At the zoo"
            },
            {
                "classId": 5701,
                "unitId": 0,
                "className": "4Where is my car"
            },
            {
                "classId": 5702,
                "unitId": 0,
                "className": "5Do you like pears"
            },
            {
                "classId": 5703,
                "unitId": 0,
                "className": "6How many"
            }
        ],
        "bookName": "人教PEP版（三起）英语三年级下册",
        "bookId": "4a9728e3090246b7b0307d72a1a644f2"
    }
}

说明：如果当前教材没有unit等级，则unitId为0，unitName为空。以此辨别该教材是一级结构还是二级结构；

返回参数说明

data字段说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
bookName string Y 教材名称
level string Y 教材层级
unit为单元
class为课程
list list Y 教材音频信息列表

list字段说明

参数 类型 是否必须 描述
unitId int N 单元ID
unitName string N 单元名称
classId int N 课程ID
className string N 课程名称

2.1.2 两层结构，输出单元

当教材为两层结构时，在请求参数中输入教材唯一标识（bookId），输出单元ID及名称（如：人教为二层结构，返回所有“unit”层级的信息列表）

请求示例

data加密前内容：

{
   "bookId": "c09ec4a1c7e34eaeb177b64800632a4b",
   "deviceId":"ai000000000003" 
}

请求参数说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
deviceId string Y 已上传至设备列表且成功激活的设备号

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "level": "unit",
        "list": [
            {
                "unitName": "1Module 1",
                "unitId": 5961
            },
            {
                "unitName": "2Module 2",
                "unitId": 5964
            },
            {
                "unitName": "3Module 3",
                "unitId": 5967
            }
        ],
        "bookName": "外研社版（一起）英语三年级下册",
        "bookId": "c09ec4a1c7e34eaeb177b64800632a4b"
    }
}

返回参数说明

data字段说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
bookName string Y 教材名称
level string Y 教材层级
unit为单元
class为课程
list list Y 教材音频信息列表

list字段说明

参数 类型 是否必须 描述
unitId int N 单元ID
unitName string N 单元名称

2.1.3 两层结构，只输出课程

当教材为两层结构时，在请求参数中输入教材唯一标识（bookId）和教材层级（level），则输出level层级的结果（如：为两层结构，请求参数中level为class，则输出结果跳过unit层级，直接返回“class”层级的信息）

请求示例

data加密前内容：

{
    "bookId": "c09ec4a1c7e34eaeb177b64800632a4b",
    "level": "class",
    "deviceId":"ai000000000003"
}

请求参数说明

参数 类型 是否必须 描述
bookId String Y 教材唯一标识
level string Y 教材层级 ,目前存在两级
unit为单元
class为课程
deviceId string Y 已上传至设备列表且成功激活的设备号

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "level": "class",
        "list": [
            {
                "classId": 5962,
                "unitName": "1Module 1",
                "unitId": 5961,
                "className": "1She's very nice"
            },
            {
                "classId": 5963,
                "unitName": "1Module 1",
                "unitId": 5961,
                "className": "2I'm going to help her"
            },
            {
                "classId": 5965,
                "unitName": "2Module 2",
                "unitId": 5964,
                "className": "1It's very long"
            }
        ],
        "bookName": "外研社版（一起）英语三年级下册",
        "bookId": "c09ec4a1c7e34eaeb177b64800632a4b"
    }
}

返回参数说明

data字段说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
bookName string Y 教材名称
level string Y 教材层级 ,目前存在两级
unit为单元
class为课程
audioist list Y 教材音频信息列表

audioist字段说明

参数 类型 是否必须 描述
unitId int Y 单元ID
unitName string Y 单元名称
classId int Y 课程ID
className string Y 课程名称

2.1.4 两层结构，指定输出课程

在请求参数中，输入教材唯一标识（bookId）和单元ID（unitId），可直接输出该单元下全部课程信息。

请求示例

data加密前内容：

{
    "bookId": "c09ec4a1c7e34eaeb177b64800632a4b",
    "unitId": 5961,
    "deviceId":"ai000000000003"
}

请求参数说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
unitId int Y 单元ID
deviceId string Y 已上传至设备列表且成功激活的设备号

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "level": "class",
        "list": [
            {
                "classId": 5962,
                "unitName": "1Module 1",
                "unitId": 5961,
                "className": "1She's very nice"
            },
            {
                "classId": 5963,
                "unitName": "1Module 1",
                "unitId": 5961,
                "className": "2I'm going to help her"
            }
        ],
        "bookName": "外研社版（一起）英语三年级下册",
        "bookId": "c09ec4a1c7e34eaeb177b64800632a4b"
    }
}

返回参数说明

data字段说明

参数 类型 是否必须 描述
bookId string Y 教材唯一标识
bookName string Y 教材名称
level string Y 教材层级 ,目前存在两级
unit为单元
class为课程
audioList list Y 教材音频信息列表

audioist字段说明

参数 类型 是否必须 描述
unitId int Y 单元ID
unitName string Y 单元名称
classId int Y 课程ID
className string Y 课程名称

2.2 获取教材内容列表中某个音频URL

当通过“获取教材音频列表”接口，获取到课程列表ID后，可通过该接口对某个课程获取音频URL

  • Method: POST
  • Content-Type: application/json
  • Path: /textBook/playItemAudioUrl

请求示例

 {
   "deviceId":"ai000000000003",
   "classId":10001
 }

参数说明

参数名 必需 类型 说明
deviceId 是 string 已上传至设备列表且成功激活的设备号
classId 是 int 专辑中单曲的id

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "audioUrl": "http://1.mp3",
        "classId": 5703,
        "unitId": 0,
        "albumId":1,
        "className": "6How many",
        "bookName": "人教PEP版（三起）英语三年级下册",
        "bookId": "4a9728e3090246b7b0307d72a1a644f2"
    }
}

参数说明

参数名 类型 是否必须 说明
audioUrl string Y 音频链接
classId int Y 专辑中单曲的id
unitId int Y 专辑中单元的id
className string Y 单曲名称
bookName string Y 教材名称
bookId int Y 教材唯一标识
albumId int Y 专辑ID，用于请求云端播放器

3.云端播放器

3.1 获取当前音频

  • Method: POST
  • Content-Type: application/json
  • Path：/textBook/getInitAudioUrl

请求示例

data加密前内容：

 {
   "deviceId":"ai000000000003",
   "albumId":5690,
 }

请求参数说明

参数 类型 是否必须 描述
deviceId String Y 已上传至设备列表且成功激活的设备号
albumId int Y 专辑id

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "bookName": "人教PEP版（三起）英语三年级下册",
        "bookId": "4a9728e3090246b7b0307d72a1a644f2",
        "albumName": "人教PEP版（三起）英语三年级下册",
        "albumId": 5690,
        "albumList": null,
        "albumVo": {
            "className": "1Welcome back to school",
            "classId": 5698,
            "audioUrl": "http://www.1.mp3",
            "select": 1,
            "isOwn": 0
        },
        "isPresent": true
    }
}

返回参数说明

参数名 类型 是否必须 说明
bookName string Y 教材名称
bookId int Y 教材唯一标识
albumName string Y 专辑名称
albumId int Y 专辑ID
albumList int Y 专辑列表
albumVo array Y 专辑信息
isPresent bool Y 设备端不需要处理

albumVo字段说明

参数名 类型 是否必须 说明
className string N 教材课程名称
classId int N 教材课程ID
audioUrl string N 音频链接
select int N 当前是否选中
0： 未选中
1：选中
isOwn int N 设备端不需要处理

3.2 播放控制

  • Method: POST
  • Content-Type: application/json
  • Path: /textBook/playNext

请求示例

data加密前内容：

 {
   "deviceId":"ai000000000003",
   "albumId":1,
   "playType":1,
   "type":0
 }

请求参数说明

参数 类型 是否必须 描述
deviceId String Y 已上传至设备列表且成功激活的设备号
albumId int Y 专辑id
playType int Y 是否循环播放
0：循环当前首；
1：循环播放列表
type int Y 上一首 /下一首标识
0：下一首；
1：上一首
autoType int N 下一首触发状态
0：手动播放下一首；
1：自动播放下一首

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "bookName": "人教PEP版（三起）英语三年级下册",
        "bookId": "4a9728e3090246b7b0307d72a1a644f2",
        "albumName": "人教PEP版（三起）英语三年级下册",
        "albumId": 5698,
        "albumList": null,
        "albumVo": {
            "className": "1Welcome back to school",
            "classId": 5698,
            "audioUrl": "null",
            "select": 1,
            "isOwn": 0
        },
        "isPresent": true
    }
}

返回参数说明

参数名 类型 是否必须 说明
bookName string Y 教材名称
bookId int Y 教材唯一标识
albumName string Y 专辑名称
albumId int Y 专辑ID
albumList int Y 专辑列表
albumVo array Y 专辑信息
isPresent bool Y 设备端不需要处理

albumVo字段说明

参数名 类型 是否必须 说明
className string N 教材课程名称
classId int N 教材课程ID
audioUrl string N 音频链接
select int N 当前是否选中
0： 未选中
1：选中
isOwn int N 设备端不需要处理

3.3 获取当前播放列表

  • Method: POST
  • Content-Type: application/json
  • Path: /textBook/getPlayList

请求示例

data加密前内容：

 {
   "deviceId":"ai000000000003",
   "albumId":1
 }

请求参数说明

参数 类型 是否必须 描述
deviceId String Y 已上传至设备列表且成功激活的设备号
albumId int Y 专辑id

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "bookName": "人教PEP版（三起）英语三年级下册",
        "bookId": "4a9728e3090246b7b0307d72a1a644f2",
        "albumName": "人教PEP版（三起）英语三年级下册",
        "albumId": 5698,
        "albumList": [
            {
                "className": "1Welcome back to school",
                "classId": 5698,
                "audioUrl": null,
                "select": 0,
                "isOwn": 0
            },
            {
                "className": "2My family",
                "classId": 5699,
                "audioUrl": null,
                "select": 1,
                "isOwn": 0
            },
            {
                "className": "3At the zoo",
                "classId": 5700,
                "audioUrl": null,
                "select": 0,
                "isOwn": 0
            },
            {
                "className": "4Where is my car",
                "classId": 5701,
                "audioUrl": null,
                "select": 0,
                "isOwn": 0
            },
            {
                "className": "5Do you like pears",
                "classId": 5702,
                "audioUrl": null,
                "select": 0,
                "isOwn": 0
            },
            {
                "className": "6How many",
                "classId": 5703,
                "audioUrl": null,
                "select": 0,
                "isOwn": 0
            }
        ]
        "isPresent": true
    }
}

返回参数说明

参数名 类型 是否必须 说明
bookName string Y 教材名称
bookId int Y 教材唯一标识
albumName string Y 专辑名称
albumId int Y 专辑ID
albumList int Y 专辑列表

albumList字段说明

参数名 类型 是否必须 说明
className string N 教材课程名称
classId int N 教材课程ID
audioUrl string N 音频链接
select int N 当前是否选中
0：未选中
1：选中
isOwn int N 设备端不需要处理

四、异常code说明

1.解密参数有误
{
    "code": 500,
    "message": "解密参数有错误",
    "data": null
}

2.apikey无相应机器人
{
    "code": 500,
    "message": "apikey错误，无相应机器人",
    "data": null
}

3.加密数据出错
{
    "code": 500,
    "message": "加密数据出错",
    "data": null
}

4.设备非法
{
    "code": 500,
    "message": "设备非法",
    "data": null
}