跳转至

生词本功能说明文档

文档状态

文件标识： TuringOS-Collection-V1.1.5
系统版本： API
完成日期： 2022年4月14日

文档修订记录

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

文档版本号 修订日期 修订原因
V1.1.1 2021.4.23 创建文档
V1.1.2 2021.5.6 删除回参的解密逻辑
V1.1.3 2021.6.9 更新正式坏境
V1.1.4 2021.8.18 将域名地址修改为http://stat.turingos.cn
在协议中增加3.1.4和3.1.5小节
在3.1.2小节中返回添加内容的id，便于通过id删除内容
V1.1.5 2022.4.14 在都3.1.5小节增加type字段（支持按类型删除生词本）
在第3.1.1小节增加content字段（支持文本查询生词本）

协议说明

1.域名地址

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

2.加密说明

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

  • 加/解密必须包含的信息：Secret（需通过图灵Biz平台 - 机器人信息页获取）；
  • 需针对请求参数中的Data字段，进行AES加密处理，具体加密方式如下：
参数 说明 备注
加密模式 CBC -
填充 PKCS5Padding -
数据块 128位（密钥为16位） -
密码 secret 需要从图灵biz平台获取
偏移量 secret 需要从图灵biz平台获取
输出 base64编码 -
字符集 utf-8 -

加/解密参考网站：http://tool.chacuo.net/cryptaes

3.接口说明

最终请求参数

{
    "key": "ed474dae62*********67050faea1788",
    "timestamp": "150******7793",
    "data": "加密后的内容"
}

3.1 生词本接口

提供单词本增删查功能，可将扫读笔识别的单词、汉字、中文句子、英文短语、英文句子收藏至单词本中，便于后续查看、操作；

3.1.1 查询生词本
  • Method: HTTP POST
  • Content-Type: application/json
  • Path:/dictionary/getCollect
加密前data数据格式：

{
    "apikey": "ba05ff********48e9",
    "deviceId": "ai*****0",
    "type": 1,
    "content": hello,
    "pageNow": 1,
    "pageSize": 5
}

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台上创建的APIKey
deviceId String Y 该APIkey下的设备号
type Integer Y 类型
0：中文
1：英文
content String N 查询文本
pageNow Integer N 当前页（默认为1）
pageSize Integer N 每页数据量（默认5）

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "total": 1,
        "datas": [
            {
                "id": 44,
                "apikey": "c89f90fa33bd4dfd88142ddc750d4c62",
                "deviceid": "c89f90fa33bd4dfd88142ddc750d4c62",
                "contentType": 1,
                "content": "good",
                "description": null,
                "createTime": "2021-08-19T03:44:53.000+0000"
            }
        ],
        "pageSize": 5,
        "type": 1,
        "pageNow": 1
    }
}

返回参数说明

参数 类型 是否必须 描述
pageNow Integer Y 当前页
pageSize Integer Y 每页数据量
total Integer Y 总数据量
datas List Y 数据详情

datas字段说明

参数 类型 是否必须 描述
id Long Y 当前内容ID
apikey String Y biz平台上创建的APIKey
deviceId String Y 该APIkey下的设备号
contentType Integer Y 类型
0：中文
1：英文
content String Y 添加的内容
createTime Long Y 添加时间
3.1.2 在生词本添加内容
  • Method: HTTP POST
  • Content-Type: application/json
  • Path:/dictionary/addCollect
加密前data数据格式：

{
    "apikey":"xxx",
    "deviceId":"ai*****0",
    "type":1,
    "content":"hello"
}

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号
type Integer Y 类型
0：中文
1：英文
content String Y 需添加的内容（最多支持1000个字符）

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "apikey": "3d96c0818bc6400fb09909cc8778698a",
        "createTime": "2021-08-11T06:25:30.492+0000",
        "description": null,
        "id": 32,
        "contentType": 1,
        "deviceid": "ai0000000000000004",
        "content": "hello5"
    }
}

若data返回null，则添加成功，否则会返回错误信息

返回参数说明

参数 类型 是否必须 描述
id Long Y 内容ID（可通过id删除内容）
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号
contentType Integer Y 类型
0：中文
1：英文
content String Y 添加的内容
createTime Long Y 添加时间
description Long Y 备注信息
3.1.3 根据id删除生词本内容
  • Method: HTTP POST
  • Content-Type: application/json
  • Path:/dictionary/deleteCollect
加密前data数据格式：

{
    "apikey":"xxx",
    "deviceId":"ai*****0",
    "ids":[1,2],
    "type":0
}

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号
ids list Y 需要删除的内容列表（输入内容ID）
type Int N 通过收藏类型进行删除
0：中文，1：英文

返回示例

解密后数据内容：

{
    "code": 200,
    "message": "success",
    "data":{
        "count":2
    }
}

返回参数说明

参数 类型 是否必须 描述
count Integer Y 删除成功个数
3.1.4 根据文本删除生词本内容
  • Method: POST
  • Content-Type: application/json
  • Path: /dictionary/deleteCollectByContent 
加密前data数据格式：

{
    "apikey":"xxx",
    "deviceId":"ai*****0",
    "ids":[hello,good]
}

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号
contents list Y 需要删除的内容列表（输入文本内容）

返回示例

{
    "code": 200,
    "message": "success",
    "data":{
        "count":2
    }
}

返回参数说明

参数 类型 是否必须 描述
count Integer 是 删除成功个数
3.1.5 根据收藏类型删除生词本
  • Method: HTTP POST
  • Content-Type: application/json
  • Path:/dictionary/deleteCollect
加密前data数据格式：

{
    "apikey":"xxx",
    "deviceId":"ai*****0",
    "type":0
}

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号
type Int N 收藏类型
0：中文，1：英文

返回示例

解密后数据内容：

{
    "code": 200,
    "message": "success",
    "data":{
        "count":2
    }
}

返回参数说明

参数 类型 是否必须 描述
count Integer Y 删除成功个数
3.1.6 删除生词本全部内容
  • Method: POST
  • Content-Type: application/json
  • Path: /dictionary/deleteAllCollect 
加密前data数据格式：

{
    "apikey":"xxx",
    "deviceId":"xxx"
}

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号（针对deviceid删除生词本内容）

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "count": 2
    }
}

返回参数说明

参数 类型 是否必须 描述
data Integer Y 删除成功个数

3.2 历史查词日志接口

历史查词日志接口可记录扫读笔每日扫词数量、具体扫读的词汇、单词本的收藏内容以及每次使用扫读笔的时长；

3.2.1 添加使用时长

请求示例

  • Method: HTTP POST
  • Content-Type: application/json
  • Path:/dictionary/addUsedTime
加密前data数据格式：

{
    "apikey":"xxx",
    "deviceId":"ai*****0",
    "usedTime":20
}
````



**请求参数说明**

| 参数     | 类型    | 是否必须 | 描述                  |
| -------- | ------- | -------- | --------------------- |
| apikey   | String  | Y        | biz平台创建的APIKey   |
| deviceId | String  | Y        | 该APIkey下的设备号    |
| usedTime | Integer | Y        | 使用时长（单位：min） |



**返回示例**

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


> 若data返回null，则添加成功，否则会返回错误信息；



##### 3.2.2 获取每次使用时长

> - Method: HTTP POST
> - Content-Type: application/json
> - Path:/dictionary/getUsedTime

加密前data数据格式：

{ "apikey":"xxx", "deviceId":"ai*0", "pageNow":1, "pageSize":5, } ````

请求参数说明

参数 类型 是否必须 描述
apikey String Y biz平台创建的APIKey
deviceId String Y 该APIkey下的设备号
pageNow Integer N 当前页（默认为1）
pageSize Integer N 每页数据量（默认5）

返回示例

{
    "total":1,
    "datas":[
        {
            "apikey":"3d96c0818bc6400fb09909cc8778698a",
            "createTime":1618907251000,
            "deviceid":"ai0000000000000004",
            "id":2,
            "usedTime":20
        }
    ],
    "pageSize":5,
    "pageNow":1
}

返回参数说明

参数 类型 是否必须 描述
pageNow Integer Y 当前页面
pageSize Integer Y 每页的数据量
total Integer Y 总数据量
datas List Y 数据详情

datas字段

参数 类型 是否必须 描述
id Long Y 数据库id
apikey String Y biz平台上创建的APIKey
deviceId String Y 该APIkey下的设备号
content Integer Y 每次使用时长
usedTime Integer Y 使用时长（单位：min）
createTime Long Y 添加时间

4.常见错误返回格式

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

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

3.缺少参数
{
    "code": 200,
    "message": "fail",
    "data": "缺少参数!"
}

参数说明

code message 是否必须 描述
code Int Y code：200为请求成功或缺少必填请求参数
code：404为apikey错误，需要使用正确apikey
code：500为解密参数错误，需查看加密方式是否有
message String Y 请求结果简述
data String Y 数据内容及说明