本文介绍灵动课堂云服务 RESTful API 的详细信息。
所有请求都发送给域名:api.agora.io。
所有请求的 Content-Type 类型为 application/json。
灵动课堂云服务 RESTful API 支持 Token 认证。你需要在发送 HTTP 请求时在 HTTP 请求头部的 x-agora-token
字段和 x-agora-uid
字段分别填入:
具体生成 RTM Token 的方法请参考生成 RTM Token 文档。
将指定用户从课堂中踢出。成功调用此接口后,服务端会触发一个用户进出课堂事件。你可通过 dirty
参数设置该用户后续是否还能再加入课堂。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
userUuid |
String | (必填)用户 uuid。这是用户的唯一标识符,也是登录 RTM 系统时使用的用户 ID。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
dirty |
Object | (选填)用户的污点设置,包含以下字段:
|
请求 URL
https://api.agora.io/edu/apps/{your_app_Id}/v2/rooms/test_class/users/123/exit
请求包体
{
"dirty": {
"state": 1,
"duration": 600
}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
设置课堂状态(未开始/开始/结束)。详见课堂状态说明。
URL 参数
需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
state |
Integer | (必填)课堂状态:0 : 未开始1 : 开始2 : 结束3 : 拖堂时间结束,房间关闭,用户无法再进入 |
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/states/1
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
"status": 200,
"body":
{
"code": 0,
"msg": "Success",
"ts": 1610450153520
}
开始或结束录制指定课堂。详见课堂录制最佳实践。
URL 参数
需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
state |
Integer | (必填)录制状态:0 : 结束1 : 开始 |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
mode |
String | (选填)录制模式:web ,则启用页面录制模式。录制生成 MP4 文件。此外,录制服务会在当前 MP4 文件时长超过 2 小时或大小超过 2 GB 时创建一个新的 MP4 文件。 |
webRecordConfig |
Object | (选填)当 mode 为 web 时,你需要通过 webRecordConfig 设置页面录制的详细信息,包含以下字段:
|
retryTimeout |
Number | 重试超时时间,单位为秒。最多重试两次。设置 retryTimeout 参数后,Agora 建议你参考课堂录制最佳实践进行操作。 |
请求 URL
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records/states/1
请求包体
{
"mode": "web",
"webRecordConfig": {
"url":"https://webdemo.agora.io/xxxxx/?userUuid={recorder_id}&roomUuid={room_id_to_be_recorded}&roleType=0&roomType=4&pretest=false&rtmToken={recorder_token}&language=en&appId={your_app_id}",
"rootUrl":"https://xxx.yyy.zzz"
},
"retryTimeout": 60
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
"status": 200,
"body":
{
"code": 0,
"ts": 1610450153520
}
在录制过程中随时调用此接口更新录制相关设置。每次调用此接口都会覆盖原先的设置。
URL 参数
需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
webRecordConfig |
Object | (选填)录制具体设置,包含以下字段:
|
请求 URL
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records/states/1
请求包体
{
"webRecordConfig": {
"onhold": false
}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
"status": 200,
"body":
{
"code": 0,
"ts": 1610450153520
}
获取指定课堂内的录制列表。
你可以通过 nextId
分批拉取,每批最多拉取 100 条数据。
URL 参数
需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
Query 参数
参数 | 类型 | 描述 |
---|---|---|
nextId |
String | (选填)下一批数据的起始 ID。第一次获取可传 null,后续获取传入响应结果里得到的 nextId 。 |
示例一:
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records?null
示例二:
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records?nextId=xxx
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
data |
Object | 具体数据,包含:
|
"status": 200,
"body":
{
"code": 0,
"msg": "Success",
"ts": 1610450153520,
"data": {
"total": 17,
"list": [
{
"recordId": "xxxxxx",
"appId": "xxxxxx",
"roomUuid": "jason0",
"startTime": 1602648426497,
"endTime": 1602648430262,
"resourceId": "xxxxxx",
"sid": "xxxxxx",
"recordUid": "xxxxxx",
"boardId": "xxxxxx",
"boardToken": "xxxxxx",
"type": 2,
"status": 2,
"url": "scenario/recording/xxxxxx/xxxxxx/xxxxxx.m3u8",
"recordDetails":[
{
"url":"xxxx/xxxx.mp4"
}
]
},
{...},
],
"count": 17
}
}
在指定课堂内上传一个公共资源。课堂内的所有用户都可以看到该课堂的公共资源。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
resourceUuid |
String | (必填)资源 uuid。这是资源的唯一标识符。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
resourceName |
String | (必填)资源名称,用于显示,长度在 64 字节以内。 |
size |
Number | (必填)资源大小,单位为字节。 |
ext |
String | (必填)资源扩展名:
|
url |
String | (必填)资源的访问地址,例如 "https://xxx.com" 。 |
conversion |
Object | (选填)如果你想要将 PPT 等资源在课堂中的白板上展示,你需要设置 conversion 将资源转换成静态图片或动态 HTML。conversion 包含以下字段:
|
请求 URL
https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources/class_file_1
请求包体
{
"resourceName": "class_file",
"size": 1024,
"ext":"ppt",
"url":"https://xxx.com",
"conversion": {
"type":"static",
"preview": false,
"scale": 1.2,
"outputFormat": ""
},
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
data |
Object 数组 | 由多个 Object 组成的数组。每个 Object 代表一个公共资源,包含以下字段:
|
{
"msg":"Success",
"code":0,
"ts":1610433913533,
"data":{
"resourceUuid": "class_file_1",
"resourceName": "class_file",
"ext": "ppt",
"size": 1024,
"url": "https://xxx.com",
"updateTime": 0,
"convert": true,
"taskUuid":"",
"taskToken":"",
"taskProgress": {
"totalPageSize": 10,
"convertedPageSize": 3,
"convertedPercentage": 30,
"convertedFileList": [{
"name": 1,
"ppt":{
"width": 1024,
"height": 960,
"src": "xxxx://xxxx.xxx.xx/xxxx.xxx",
"preview": "xxxx://xxxx.xxx.xx/xxxx.xxx",
}
},{...}],
"currentStep": "Extracting"
}
}
}
删除指定课堂内的一个或多个公共资源。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
resourceUuids |
String 数组 | (必填)由资源 uuid 组成的数组。资源 uuid 是资源的唯一标识符。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求 URL
https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources
请求包体
{
"resourceUuids": ["uuid1","uuid2"]
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg":"Success",
"code":0,
"ts":1610433913533
}
获取指定课堂内的所有公共资源。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求 URL
https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
data |
Object 数组 | 由多个 Object 组成的数组。每个 Object 代表一个公共资源,包含以下字段:
|
{
"msg":"Success",
"code":0,
"ts":1610433913533,
"data":[{
"resourceUuid": "",
"resourceName": "",
"ext": "",
"size": 0,
"url": "",
"updateTime": 0,
"convert": true,
"taskUuid":"",
"taskToken":"",
"taskProgress": {
"totalPageSize": 10,
"convertedPageSize": 3,
"convertedPercentage": 30,
"convertedFileList": [{
"name": 1,
"ppt":{
"width": 1024,
"height": 960,
"src": "xxxx://xxxx.xxx.xx/xxxx.xxx",
"preview": "xxxx://xxxx.xxx.xx/xxxx.xxx",
}
},{...}],
"currentStep": "Extracting"
}
}]
}
查询指定课堂内指定类型的事件。
你可以通过 nextId
分批查询,每批最多查询 100 条数据。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
Query 参数
参数 | 类型 | 描述 |
---|---|---|
nextId |
String | (选填)下一批数据的起始 ID。第一次获取可传 null,后续获取传入响应结果里得到的 nextId 。 |
cmd |
Integer | (选填)事件类型,详见事件枚举。 |
请求 URL
示例一:
https://api.agora.io/edu/apps/{appId}/v2/rooms/test_class/sequences?null&cmd=1
示例二:
https://api.agora.io/edu/apps/{appId}/v2/rooms/test_class/sequences?nextId=50&cmd=1
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
data |
Object | 具体数据,包含:
|
{
"msg":"Success",
"code":0,
"ts":1610433913533,
"data":{
"total":1,
"list":[
{
"roomUuid": "",
"cmd": 20,
"sequence": 1,
"version": 1,
"data":{}
}
],
"nextId": null,
"count":1
}
}
在服务端获取指定 App ID 下所有课堂中发生的事件。
你可定时轮询该接口来监听灵动课堂中发生的事件。
URL 参数
需要在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
https://api.agora.io/edu/polling/apps/{yourappId}/v2/rooms/sequences
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
data |
Object | 具体数据,包含:roomUuid : String 型,课堂 uuid。cmd : Integer 型,事件类型。详见事件枚举。sequence : Integer 型。事件序号,是每个课堂内事件的唯一标识符,课堂内全局自增,用于确保事件的有序性。version : Integer 型,版本号。data : Object 型,事件的具体数据,取决于事件类型。详见事件枚举。 |
"status": 200,
"body":
{
"msg": "Success",
"code": 0,
"ts": 1610167740309,
"data":[
{
"roomUuid": "xxxxxx",
"cmd": 20,
"sequence": 1,
"version": 1,
"data":{}
}
]
}
新增或更新指定课堂的自定义属性,详见如何设置自定义用户属性和课堂属性?
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
properties |
Object | 课堂属性。 |
cause |
Object | 更新原因。 |
请求包体
{
"properties" :{
"key1":"value1",
"key2":"value2"
},
"cause":{}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除指定课堂的自定义属性,详见如何设置自定义用户属性和课堂属性?
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
properties |
String 数组 | 课堂属性。 |
cause |
Object | 删除原因。 |
请求包体
{
"properties" :[
"key1",
"key2"
],
"cause":{}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
新增或更新指定用户的自定义属性,详见如何设置自定义用户属性和课堂属性?
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
userUuid |
String | (必填)用户 uuid。这是用户的唯一标识符,也是登录 RTM 系统时使用的用户 ID。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
properties |
Object | 用户属性。 |
cause |
Object | 更新原因。 |
请求包体
{
"properties" :{
"key1":"value1",
"key2":"value2"
},
"cause":{}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除指定用户的自定义属性,详见如何设置自定义用户属性和课堂属性?
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
userUuid |
String | (必填)用户 uuid。这是用户的唯一标识符,也是登录 RTM 系统时使用的用户 ID。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
properties |
String 数组 | 用户属性。 |
cause |
Object | 删除原因。 |
请求包体
{
"properties" :[
"key1",
"key2"
],
"cause":{}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
新增或更新指定课堂内 extApp 的属性。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
extAppUuid |
String | (必填)extApp 的 uuid。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
properties |
Object | 用户属性。 |
common |
Object | 包含以下字段:state : Integer 型,extApp 的状态,0 表示关闭,1 表示开启。 |
cause |
Object | 更新原因。 |
请求包体
{
"properties" :{},
"common":{
"state":0
},
"cause":{}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除指定课堂内 extApp 的属性。
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
extAppUuid |
String | (必填)extApp 的 uuid。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
请求包体参数
在请求包体中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
properties |
String 数组 | 用户属性。 |
cause |
Object | 删除原因。 |
请求包体
{
"properties" :[
"key-path1",
"key-path2"
],
"cause":{}
}
参数 | 类型 | 描述 |
---|---|---|
code |
Integer | 业务状态码: |
msg |
String | 详细信息。 |
ts |
Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
Query 参数
参数 | 类型 | 描述 |
---|---|---|
nextId |
String | (选填)下一批数据的起始 ID。第一次获取可传 null,后续获取传入响应结果里得到的 nextId 。 |
count |
Integer | (选填)本批数据条数,默认值为 100。 |
不同情况下 data
中返回的字段不同,具体如下:
老师开启答题后,答题器的汇总数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.correctItems | Object[] | 正确选项 |
changeProperties.extra.correctCount | Integer | 本题答对人数 |
changeProperties.extra.answerState | Integer | 本次答题状态:
|
changeProperties.extra.receiveQuestionTime | Long | 收到题目时间 |
changeProperties.extra.popupQuizId | String | 题目 ID |
changeProperties.extra.averageAccuracy | Float | 本题正确率 |
changeProperties.extra.totalCount | Integer | 本题回答总人数 |
changeProperties.extra.items | Object[] | 本题的所有选项 |
changeProperties.state | Integer | 答题器状态:
|
cause | String | 属性变更原由,答题器为 popupQuiz |
operator | Object | 操作人 |
operator.userUuid | String | 用户 ID |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
学生提交答案后,该学生的答题数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.lastCommitTime | Long | 最后一次提交时间 |
changeProperties.popupQuizId | String | 题目 ID |
changeProperties.selectedItems | Object[] | 该学生提交的答案 |
changeProperties.isCorrect | Boolean | 该学生提交的答案是否正确 |
cause | String | 属性变更原由,答题器为 popupQuiz |
operator | Object | 操作人 |
operator.userUuid | String | 用户 uuid |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
fromUser | Object | 发起本次答题的用户 |
fromUser.userUuid | String | 用户 ID |
fromUser.userName | String | 用户名称 |
fromUser.role | String | 用户角色 |
学生提交答案后,答题器的汇总数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.selectedCount | Integer | 已经答题人数 |
changeProperties.extra.correctCount | Integer | 本题答对人数 |
changeProperties.extra.averageAccuracy | Float | 本题正确率 |
changeProperties.extra.totalCount | Integer | 本题回答总人数 |
cause | String | 属性变更原由,答题器为 popupQuiz |
operator | Object | 操作人 |
operator.userUuid | String | 用户 ID |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
老师结束答题后,答题器的汇总数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.selectedCount | Integer | 已经答题人数 |
changeProperties.extra.correctCount | Integer | 本题答对人数 |
changeProperties.extra.answerState | Integer | 本次答题状态:
|
changeProperties.extra.averageAccuracy | Float | 本题正确率 |
changeProperties.extra.totalCount | Integer | 本题回答总人数 |
cause | String | 属性变更原由,答题器为 popupQuiz |
operator | Object | 操作人 |
operator.userUuid | String | 用户 uuid |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
老师开启答题后,答题器的汇总数据发生变化:
"action": NumberInt("1"),
"changeProperties": {
"widgets.popupQuiz.extra.correctItems": [
"A",
"B",
"D"
],
"widgets.popupQuiz.extra.totalCount": NumberInt("1"),
"widgets.popupQuiz.extra.answerState": NumberInt("1"),
"widgets.popupQuiz.state": NumberInt("1"),
"widgets.popupQuiz.extra.popupQuizId": "ab5b183238a74d5a9c955dc87c6397e0",
"widgets.popupQuiz.extra.averageAccuracy": 0,
"widgets.popupQuiz.extra.correctCount": NumberInt("0"),
"widgets.popupQuiz.extra.items": [
"A",
"C",
"B"
],
"widgets.popupQuiz.extra.receiveQuestionTime": NumberLong("1652413962895")
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
学生提交答案后,该学生的答题数据发生变化:
"action": NumberInt("1"),
"changeProperties": {
"widgets.popupQuiz.selectedItems": [
"A",
"B",
"D"
],
"widgets.popupQuiz.isCorrect": true,
"widgets.popupQuiz.popupQuizId": "ab5b183238a74d5a9c955dc87c6397e0",
"widgets.popupQuiz.lastCommitTime": NumberLong("1652413989997")
},
"fromUser": {
"userName": "yerongzhe2",
"userUuid": "yerongzhe22",
"role": "audience"
}
老师结束答题后,答题器的汇总数据发生变化:
"action": NumberInt("1"),
"changeProperties": {
"widgets.popupQuiz.extra.totalCount": NumberInt("1"),
"widgets.popupQuiz.extra.answerState": NumberInt("0"),
"widgets.popupQuiz.extra.selectedCount": NumberInt("1"),
"widgets.popupQuiz.extra.averageAccuracy": 1,
"widgets.popupQuiz.extra.correctCount": NumberInt("1")
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
URL 参数
在 URL 中传入以下参数。
参数 | 类型 | 描述 |
---|---|---|
appId |
String | (必填)Agora App ID。 |
roomUUid |
String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符): |
Query 参数
参数 | 类型 | 描述 |
---|---|---|
nextId |
String | (选填)下一批数据的起始 ID。第一次获取可传 null,后续获取传入响应结果里得到的 nextId 。 |
count |
Integer | (选填)本批数据条数,默认值为 100。 |
不同情况下 data
中返回的字段不同,具体如下:
老师开启投票后,投票器的汇总数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.mode | Integer | 投票模式:
|
changeProperties.extra.pollingState | Integer | 本次投票状态:
|
changeProperties.extra.pollDetails | Map<String,Object> | 投票详情,key 为选项索引,从 0 开始。 |
changeProperties.extra.pollDetails.num | Integer | 选择该选项的人数 |
changeProperties.extra.pollDetails.percentage | Float | 选择该选项的人数所占百分比 |
changeProperties.extra.pollId | String | 本次投票 ID |
changeProperties.extra.pollItems | Object[] | 选项内容 |
changeProperties.state | Integer | 投票器状态:
|
cause | String | 属性变更原由,投票器为 poll |
operator | Object | 操作人 |
operator.userUuid | String | 用户 ID |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
学生提交选项后,该学生的投票数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.pollId | String | 本次投票 ID |
changeProperties.extra.selectIndex | Object[] | 该学生选择的选项的索引 |
cause | String | 属性变更原由,投票器为 poll |
operator | Object | 操作人 |
operator.userUuid | String | 用户 ID |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
fromUser | Object | 发起本次投票的用户 |
fromUser.userUuid | String | 用户 ID |
fromUser.userName | String | 用户名称 |
fromUser.role | String | 用户角色 |
学生提交选项后,投票器的汇总数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.pollDetails | Map<String,Object> | 投票详情,key 为选项索引,从 0 开始。 |
changeProperties.extra.pollDetails.num | Integer | 选择该选项的人数 |
changeProperties.extra.pollDetails.percentage | Float | 选择该选项的人数所占百分比 |
changeProperties.extra.pollId | String | 本次投票 ID |
cause | String | 属性变更原由,投票器为 poll |
operator | Object | 操作人 |
operator.userUuid | String | 用户 ID |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
老师结束投票后,投票器的汇总数据会发生变化,data
中包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
action | Integer | 操作类型 |
changeProperties | Object | 发生变更的属性 |
changeProperties.extra | Object | 属性补充信息 |
changeProperties.extra.pollingState | Integer | 本次投票状态:
|
changeProperties.extra.pollDetails | Map<String,Object> | 投票详情,key 为选项索引,从 0 开始。 |
changeProperties.extra.pollDetails.num | Integer | 选择该选项的人数 |
changeProperties.extra.pollDetails.percentage | Float | 选择该选项的人数所占百分比 |
changeProperties.extra.pollId | String | 本次投票 ID |
cause | String | 属性变更原由,投票器为 poll |
operator | Object | 操作人 |
operator.userUuid | String | 用户 ID |
operator.userName | String | 用户名称 |
operator.role | String | 用户角色 |
老师开启投票后,投票器的汇总数据发生变化:
"action": NumberInt("1"),
"changeProperties": {
"widgets.poll.extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"widgets.poll.extra.pollState": NumberInt("1"),
"widgets.poll.extra.pollItems": [
"aaa",
"bbb",
"ccc",
"ddd",
"eee"
],
"widgets.poll.extra.mode": NumberInt("2"),
"widgets.poll.state": NumberInt("1"),
"widgets.poll.extra.pollDetails": {
"0": {
"num": NumberInt("0"),
"percentage": 0
},
"1": {
"num": NumberInt("0"),
"percentage": 0
},
"2": {
"num": NumberInt("0"),
"percentage": 0
},
"3": {
"num": NumberInt("0"),
"percentage": 0
},
"4": {
"num": NumberInt("0"),
"percentage": 0
}
}
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
学生提交选项后,该学生的投票数据发生变化:
"action": NumberInt("1"),
"changeProperties": {
"widgets.poll.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"widgets.poll.selectIndex": [
NumberInt("1"),
NumberInt("2"),
NumberInt("4")
]
},
"fromUser": {
"userName": "yerongzhe2",
"userUuid": "yerongzhe22",
"role": "audience"
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
学生提交选项后,投票器的汇总数据发生变化:
"action": NumberInt("1"),
"changeProperties": {
"widgets.poll.extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"widgets.poll.extra.pollDetails": {
"0": {
"num": NumberInt("0"),
"percentage": 0
},
"1": {
"num": NumberInt("1"),
"percentage": 1
},
"2": {
"num": NumberInt("1"),
"percentage": 1
},
"3": {
"num": NumberInt("0"),
"percentage": 0
},
"4": {
"num": NumberInt("1"),
"percentage": 1
}
}
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
老师结束投票后,投票器的汇总数据会发生变化,data
中包含以下字段:
"action": NumberInt("1"),
"changeProperties": {
"widgets.poll.extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"widgets.poll.extra.pollState": NumberInt("0"),
"widgets.poll.extra.pollDetails": {
"0": {
"num": NumberInt("0"),
"percentage": 0
},
"1": {
"num": NumberInt("1"),
"percentage": 1
},
"2": {
"num": NumberInt("1"),
"percentage": 1
},
"3": {
"num": NumberInt("0"),
"percentage": 0
},
"4": {
"num": NumberInt("1"),
"percentage": 1
}
}
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
HTTP 响应状态码 | 业务状态码 | 描述 |
---|---|---|
200 | 0 | 请求成功。 |
400 | 400 | 请求的参数错误。 |
401 | N/A | 可能的原因:x-agora-uid 和 x-agora-token 错误或不匹配。 |
403 | 30403200 | 课堂已禁言,无法发送聊天消息。 |
404 | N/A | 服务器无法找到请求的资源。 |
404 | 20404100 | 课堂不存在。 |
404 | 20404200 | 用户不存在。 |
409 | 30409410 | 录制状态冲突,录制未开始。 |
409 | 30409411 | 录制状态冲突,录制未结束。 |
409 | 30409100 | 课程状态冲突,课程已开始。 |
409 | 30409101 | 课程状态冲突,课程已结束。 |
500 | 500 | 服务器内部错误,无法完成请求。 |
503 | N/A | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取响应。 |