技术接口规范

基础介绍
身份识别规范
数据回传接口
开发参考

平台介绍

关于虚拟实验平台

虚拟实验平台是一款为教育机构量身打造的在线实验教学系统，旨在为学生提供丰富多样的虚拟实验环境，使学生能够在没有实体实验设备的情况下，通过网络完成各种实验项目。

平台特点

高性能模拟

采用先进的仿真技术，提供接近真实的实验体验

多人协作

支持多人同时参与实验，促进团队合作

数据分析

自动记录实验数据，支持多维度分析和可视化

云端存储

实验数据云端存储，随时随地访问和查看

快速开始

快速开始内容区域，这里将展示如何快速上手使用平台。

虚拟仿真实训课程项目技术接口规范

一、技术接口说明

服务"虚拟仿真实验教学项目共享平台"（以下简称：虚仿实验平台）的用户与学校实验教学项目的用户管理系统之间的身份自动识别，避免二次登录。识别后的用户在学校实验教学项目上的实验操作状态和产生的实验结果数据，将自动回传到虚仿实验平台，支撑数据统计和监测。

用户身份识别

实验操作

数据回传

用户身份识别规范

用户身份识别是实现无缝对接的重要环节，通过令牌验证和用户信息交换，确保用户可以在不同平台间顺畅切换。

获取令牌

2.1 获取令牌

当用户登录"虚仿实验平台"后点击【开始实验】时（如下图所示），"虚仿实验平台"会以参数形式提供 project。

示例 
http://{申报项目平台实验地址}?project=project

2.2 获取用户信息和access_token

access_token 是接口调用的凭据，access_token 的有效期为接口返回过期时间："expirse_time"。

2.2.1 接口调用请求说明

POST/GET
/open/api/v2/token?project=PROJECT&appid=APPID&signature=SIGSIGNAT

2.2.2 调用参数说明

参数 说明
appid 由"虚仿实验平台"分配给各实验平台的唯一编号
signature MD5(PROGECT+ APPID+SECRET)
PROGECT是步骤 2.1 中获取的令牌
APPID 是由"虚仿实验平台"分配给各实验平台的唯一编号
SECRET 是由"虚仿实验平台"分配给各实验平台的密钥
project 步骤 2.1 中获取的令牌

返回参数说明

参数 说明
access_token 接口调用凭证
create_time access_token 创建时间，10位时间戳
expires_time 过期时间，10 位时间戳
create_at 示例：2020-08-24 08:54:21
expires_at 示例：2020-08-24 10:54:21
un 用户名
dis 用户姓名
错误时的返回示例 
{"code":1,"msg":"参数错误"}

返回码说明

返回码 说明
0 调用成功，返回所需数据
1 参数错误
2 无效的appid
3 signature 验证失败
4 access_token签名错误
5 access_token 已过期
其他 系统错误或非法操作

刷新令牌

2.3 重新获取access_token

access_token 的有效期目前为24个小时，过期需要重新获取。如果实验时间超过24小时，请在学生完成实验后向虚仿实验平台返回实验成绩时，重新获取新的 access_token。

注意：调用此接口获取的 access_token，不支持再次通过此接口获取新的 access_token，原 access_token 最多可有 2 次机会获取新的 access_token。

2.3.1 接口调用请求说明

POST/GET
/open/api/v2/token/refresh?access_token=ACCESS_TOKEN&appid=APPID&signature=SIGNATURE

注：当 access_token 失效以后，调用接口重新获取新的 access_token。

参数 说明
appid 由"虚仿实验平台"分配给各实验平台的唯一编号
signature MD5(ACCESS_TOKEN+ APPID+SECRET)
注：ACCESS_TOKEN 是步骤 2.2 中获取的 access_token
APPID 是由"虚仿实验平台"分配给各实验平台的唯一编号
SECRET 是由"虚拟实验平台"分配给各实验平台的密钥
access_token 调用"获取用户信息"接口时返回的 access_token。注意，最多可有 2 次机会获取新的 access_token。

2.3.2 调用URL示例

示例URL 
/open/api/v2/token/refresh?access_token=4hCwDHmIAf8Bj%2BTVe7GBVUaLOY0rJiDyWtCmNhixIsBJnZLiAPhmYc0vBLr592Zj&appid=100400&signature=2D6BD62EC95ABA47B0BDA93FAD7F6744
正确时的返回JSON数据包 
{
    "code": 0,
    "access_token": "4hCwDHmIAf8Bj+TVe7GBVUaLOY0rJiDyWtCmNhixIsBJnZLiAPhmYc0vBLr592Zj",
    "create_time": 1598230461,
    "create_at": "2020-08-2408:54:21",
    "expires_time": 1598237661,
    "expires_at": "2020-08-24 10:54:21"
}

返回参数说明

参数 说明
access_token 接口调用凭证
create_time access_token 创建时间，10位时间戳
expires_time 过期时间，10 位时间戳
create_at 示例：2020-08-24 08:54:21
expires_at 示例：2020-08-24 10:54:21

实验结果数据回传接口

回传数据接口是指："虚仿实验平台"用户完成实验教学项目后，所产生的实验结果数据。如果有实验报告，则先调用附件上传接口，然后再将这些数据和用户信息一起通过回传数据接口同步至"虚仿实验平台"。

3.1 接口调用请求说明

POST
/open/api/v2/data_upload?access_token=ACCESSTOKEN

3.2 请求示例

JSON请求示例 
{
"username":"用户名",
"title":"实验名称", 
"status":1,
"score":80,
"startTime": 1522646936000, 
"endTime":1522647936000,
"timeUsed": 900,
"appid": "slg6257efaf4a663",
"originId":1,
"steps":[
    {
        "seq": 1,
        "title": "实验步骤 1",
        "startTime": 1522646936000,
        "endTime": 1522647936000,
        "timeUsed": 900, 
        "expectTime":2, 
        "maxScore":10, 
        "score":10, 
        "repeatCount":1, 
        "evaluation":"优"
    },
    ...
]
}

① 实验数据回传字典

字段 字段名称 类型 是否必填 备注
username 用户名 String 是 平台账号
title 实验名称 String 是 用户学习的实验名称
status 实验结果 Int 是 1：完成；2：未完成
score 实验成绩 Int 是 0~100，百分制
startTime 实验开始时间 Time 是 13位时间戳
endTime 实验结束时间 Time 是 13位时间戳
timeUsed 实验用时 Int 是 分钟
appid 接入平台编号 Int 是 由"虚仿实验平台"分配给实验教学项目的编号
originId 实验平台实验记录ID String 是 二级平台唯一，用于对应实验报告
steps 实验步骤记录 Array 是 详见《实验步骤记录》说明

② 实验步骤记录说明

参数 字段名称 类型 是否必填 备注
seq 实验步骤序号 Int 是
title 步骤名称 String 是 100字以内
startTime 实验步骤开始时间 Time 是 13位时间戳，采用utc-8时区
endTime 实验步骤结束时间 Time 是 13位时间戳，采用utc-8时区
timeUsed 实验步骤用时 Int 是 单位秒
expectTime 实验步骤合理用时 Int 是 单位秒
maxScore 实验步骤满分 Int 是 0~100，百分制
score 实验步骤得分 Int 是 0~100，百分制
repeatCount 实验步骤操作次数 Int 是
evaluation 步骤评价 String 是 200字以内
scoringModel 赋分模型 String 是 200字以内
remarks 备注 String 否 200字以内

3.3 调用URL示例

URL示例 
/open/api/v2/data_upload?access_token=4hCwDHmIAf8Bj%2BTVe7GBVUaLOY0rJiDyWtCmNhixIsBJnZLiAPhmYc0vBLr592Zj
正确时的返回JSON数据包 
{"code":0,"id":"1"}
错误时的返回JSON数据包（示例为参数缺失） 
{"code":1,"msg":"参数错误"}

返回码说明

返回码 说明
0 调用成功
1 缺少 access_token
2 access_token 签名错误
3 access_token 已过期
4 其他错误
5 字段错误
6 无效的 appid
7 originId 已存在
8 未知的实验用户
9 试验状态只能是完成[1]或者未完成[2]
10 分数的范围值应在 0 - 100
11 startTime 时间戳长度有应为13
12 endTime 时间戳长度有应为13
13 实验步骤不能超过 200 步
14 用户信息与access_token 不一致
15 appid 与access_token 所含信息不一致
其他值 系统错误或非法操作

附件上传接口

3.4 附件上传接口

POST
/open/api/v2/attachment_upload?access_token=ACCESS_TOKEN&appid=APPID&originId=ORIGINID&filename=FILENAME&title=TITLE&remarks=REMARKS

参数说明

参数 说明
access_token 接口调用令牌
appid 由"虚拟实验平台"分配给实验教学课程的编号
originId 实验平台实验记录ID
filename 上传文件的名称，需要带文件扩展名，如：实验报告.pdf，请使用 urlEncode 对 FILENAME 进行处理
title 实验报告名称，请使用 urlEncode 对TITLE 进行处理
remarks 备注，请使用 urlEncode 对remarks 进行处理

3.5 调用URL示例

URL示例 
/open/api/v2/attachment_upload?access_token=8%2Bm%2FpSd2FyZzBmWtmJQ8U2wse2ws9r%2FZQKQyeG4TNJFZhvXX
正确时的返回JSON数据包 
{"code":0,"id":"1"}
错误时的返回JSON数据包（示例为参数错误） 
{"code":1,"msg":"参数错误"}

返回码说明

返回码 说明
0 调用成功
1 缺少 access_token
2 access_token 签名错误
3 access_token 已过期
4 其他错误
5 字段错误，缺少参数
6 无效的 appid
7 appid 与access_token 所含信息不一致
8 originId 数据不存在
9 重复上传实验报告
10 实验报告已存在
11 上传附件失败提示的错误
其他值 系统错误或非法操作