灵动课堂服务端 API
灵动课堂提供了多种服务端对服务端 RESTful API(包括但不限于房间管理、用户管理、事件同步、扩展组件等),供开发者灵活扩展课堂功能及与自身业务系统的快速对接,大幅降低开发门槛,轻松实现复杂应用逻辑,为企业、学校提供高稳定高性价比的线上互动课堂服务。
公共请求参数
公共参数是用于标识用户 App ID 和接口签名的参数和请求区域,如非必要,在每个接口单独的文档中不再对这些参数进行说明,但每次请求均需要携带这些参数,才能正常发起请求。
域名
所有请求都发送给域名 api.sd-rtn.com
。
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供切换域名的方案,建议在请求超时或 HTTP 状态为 50x
时切换域名。重试详情请参考切换域名。
数据格式
所有请求的 Content-Type 类型为 application/json
。
认证方式
在使用灵动课堂 RESTful API 前,你需要通过 HTTP Token 认证。
灵动课堂同时支持 AccessToken2(推荐)和 AccessToken(兼容)两种方式,你可以选择任意一种。本文的示例请求都使用 AccessToken2。
AccessToken2
如果你使用的是 AccessToken2,那么你需要在 HTTP 请求中 header 的 Authorization: agora token=
字段填入服务端生成的 RTM Token。
示例代码如下:
- Java
- Golang
- node.js
- Python
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// 基于 Java 实现的 HTTP 基本认证示例,使用 RTC 的服务端 RESTful API
class TokenAuthExample {
public static void main(String[] args) throws IOException, InterruptedException {
// 请输入你生成的 RTM Token
final String tokenValue = "input your token value here";
// 请输入你的 AppID
final String appID = "input your app ID here";
String urlStr = String.format("https://api.agora.io/dev/v2/project/%s/rtm/vendor/user_events", appID);
String authValue = String.format("agora token=%s", tokenValue);
// 创建 HTTP 请求对象
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(urlStr))
.GET()
.header("Authorization", authValue)
.header("Content-Type", "application/json")
.build();
// 发送 HTTP 请求
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
if err := tokenAuthExamle(); err != nil {
panic(err)
}
}
// 基于 Golang 实现的 HTTP Token 认证示例,使用 RTC 的服务端 RESTful API
func tokenAuthExamle() error {
var (
// 输入你生成的 Token
tokenValue = "input the token value here"
// 输入你的 AppID
appID = "input your app ID here"
urlstr = fmt.Sprintf("https://api.agora.io/dev/v2/project/%s/rtm/vendor/user_events", appID)
authValue = fmt.Sprintf("agora token=%s", tokenValue)
)
// 构造 HTTP 请求
req, err := http.NewRequest(http.MethodGet, urlstr, nil)
if err != nil {
return fmt.Errorf("failed to new http request, %w", err)
}
// 设置 Authorization header
req.Header.Set("Authorization", authValue)
req.Header.Set("Content-Type", "application/json")
// 发送 HTTP 请求
resp, err := http.DefaultClient.Do(req)
if err != nil {
return fmt.Errorf("failed to send request, %w", err)
}
defer resp.Body.Close()
// 读取响应体
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return fmt.Errorf("failed to read response body, %w", err)
}
// 判定 StatusCode
if resp.StatusCode/100 != 2 {
return fmt.Errorf("StatusCode(%d) != 2xx, %s", resp.StatusCode, string(body))
}
// 打印出正常返回的响应体
fmt.Println(string(body))
return nil
}
// 基于 node.js 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
const https = require('https')
// 请输入你生成的 RTM Token
var token_value = "input your token here"
// 请输入你的 AppID
var app_id = "input your app ID"
var url_path = `/dev/v2/project/${app_id}/rtm/vendor/user_events`
var auth_token = `agora token=${token_value}`
// 设置请求参数
const options = {
hostname: 'api.agora.io',
port: 443,
path: url_path,
method: 'GET',
headers: {
// 在 header 中添加 Authorization 字段
'Authorization': auth_token,
'Content-Type': 'application/json'
}
}
const req = https.request(options, res => {
console.log(`Status code: ${res.statusCode}`)
res.on('data', d => {
process.stdout.write(d)
})
})
req.on('error', error => {
console.error(error)
})
req.end()
import http.client
# 基于 Python 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
# 请输入你生成的 Token
token_value = "input your token here"
# 请输入你的 AppID
app_id = "input your app ID here"
url_path = "/dev/v2/project/{0}/rtm/vendor/user_events".format(app_id)
auth_value = "agora token={0}".format(token_value)
# 通过基本 URL 创建连接对象
conn = http.client.HTTPSConnection("api.agora.io")
# 创建 header
headers = {}
# 添加鉴权 header
headers['Authorization'] = auth_value
headers['Content-Type'] = 'application/json'
payload = ""
# 发送请求
conn.request("GET", url_path, payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
AccessToken
如果你使用的是 AccessToken,那么你需要在发送 HTTP 请求时在 HTTP 请求中 header 的 x-agora-token
字段和 x-agora-uid
字段分别填入:
- 服务端生成的 RTM Token。
- 生成 RTM Token 时使用的 UID。
示例代码如下:
- Java
- Golang
- PHP
- C#
- node.js
- Python
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
// 基于 Java 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
public class Base64Encoding {
public static void main(String[] args) throws IOException, InterruptedException {
// RTM Token
String tokenHeader = "Your RTM token";
// 生成 RTM Token 时使用的 user ID
String uidHeader = "test_user";
HttpClient client = HttpClient.newHttpClient();
// 构建请求对象
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events"))
.GET()
// 在 header 中添加 x-agora-token 字段
.header("x-agora-token", tokenHeader )
// 在 header 中添加 x-agora-uid 字段
.header("x-agora-uid", uidHeader)
.header("Content-Type", "application/json")
.build();
// 发送请求
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
// 基于 Golang 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
func main() {
// RTM Token
tokenHeader := "Your RTM Token"
// 生成 RTM Token 时使用的 user ID
uidHeader := "test_user"
url := "https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events"
method := "GET"
payload := strings.NewReader(``)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
// 在 header 中添加 x-agora-token 字段
req.Header.Add("x-agora-token", tokenHeader)
// 在 header 中添加 x-agora-uid 字段
req.Header.Add("x-agora-uid", uidHeader)
req.Header.Add("Content-Type", "application/json")
// 发送请求
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
<?php
// 基于 PHP 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
// RTM Token
$token = "Your RTM Token";
// 生成 RTM Token 时使用的 user ID
$uid = "test_user";
// 在 header 中添加 x-agora-token 字段
$token_header = "x-agora-token: " . $token;
// 在 header 中添加 x-agora-uid 字段
$uid_header = "x-agora-uid: " . $uid;
$curl = curl_init();
// 发送请求
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
$token_header,
$uid_header,
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
if($response === false) {
echo "Error in cURL : " . curl_error($curl);
}
curl_close($curl);
echo $response;
using System;
using System.IO;
using System.Net;
using System.Text;
// 基于 C# 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
namespace Examples.System.Net
{
public class WebRequestPostExample
{
public static void Main()
{
// RTM Token
string token = "Your RTM Token";
// 生成 RTM Token 时使用的 user ID
string uid = "userA";
// 在 header 中添加 x-agora-token 字段
string tokenHeader = "x-agora-token: " + token;
// 在 header 中添加 x-agora-uid 字段
string uidHeader = "x-agora-uid: " + uid;
WebRequest request = WebRequest.Create("https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events");
request.Method = "GET";
// 在请求中添加 header
request.Headers.Add(tokenHeader);
request.Headers.Add(uidHeader);
request.ContentType = "application/json";
// 获取响应
WebResponse response = request.GetResponse();
Console.WriteLine(((HttpWebResponse)response).StatusDescription);
using (Stream dataStream = response.GetResponseStream())
{
StreamReader reader = new StreamReader(dataStream);
string responseFromServer = reader.ReadToEnd();
Console.WriteLine(responseFromServer);
}
response.Close();
}
}
}
// 基于 node.js 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
const https = require('https')
// RTM Token
token = "Your RTM Token"
// 生成 RTM Token 时使用的 user ID
uid = "test_user"
// 设置请求参数
const options = {
hostname: 'api.agora.io',
port: 443,
path: '/dev/v2/project/<Your App ID>/rtm/vendor/user_events',
method: 'GET',
headers: {
// 在 header 中添加 x-agora-token 字段
'x-agora-token':token,
// 在 header 中添加 x-agora-uid 字段
'x-agora-uid': uid,
'Content-Type': 'application/json'
}
}
const req = https.request(options, res => {
console.log(`Status code: ${res.statusCode}`)
res.on('data', d => {
process.stdout.write(d)
})
})
req.on('error', error => {
console.error(error)
})
req.end()
import http.client
# 基于 Python 实现的 Token 认证示例,使用 RTM 的用户事件 RESTful API
# 通过基本 URL 创建连接对象
conn = http.client.HTTPSConnection("api.agora.io")
# 创建 header
headers = {}
# 为 header 添加 x-agora-token 字段,内容为 RTM Token
headers['x-agora-token'] = "Your RTM Token"
# 为 header 添加 x-agora-uid 字段,内容为生成 RTM Token 时使用的 user ID
headers['x-agora-uid'] = "test_user"
headers['Content-Type'] = 'application/json'
payload = ""
# 发送请求
conn.request("GET", "/dev/v2/project/<Your App ID>/rtm/vendor/user_events", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
区域
灵动课堂 RESTful API 所有接口 region
字段的可选值如下表所示。如果有接口不支持该表中的所有区域,则会在该接口文档中单独说明。
对于同一课堂,服务端接口调用的区域需要与客户端课堂创建的区域一致,否则会报告“房间不存在”的错误。
取值 | 区域 |
---|---|
cn | 中国大陆 |
ap | 亚太 |
na | 北美 |
eu | 欧洲 |
其他业务参数
参数 | 类型 | 描述 |
---|---|---|
appId | String | 声网 App ID,详见获取 App ID。 |
roomUuid | String | 课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制,长度需在50字符内。 以下为支持的字符集范围(共 89 个字符):
|
userUuid | String | 用户 uuid。这是用户的唯一标识符,也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
公共响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码:
|
msg | String | 接口响应文字信息。 |
ts | Number | 当前服务端的 Unix 时间戳,UTC 时间,单位为毫秒。 |
data | Object | 返回数据,部分接口的该字段有值,详见单个接口的说明。 |
响应示例
成功返回结果
当接口请求成功时,所有接口响应的 HTTP 状态码均为 200
。
"status": 200,
"body":
{
"code": 0,
"msg": "Success",
"ts": 1610450153520
}
错误返回结果
若为客户端错误,HTTP 状态码(status
字段)为 40x
。
"status": 404,
"body":
{
"code": 20404100,
"msg": "Room not exists!",
"ts": 1610450153520
}
若为服务端错误,HTTP 状态码(status
字段)为 50x
。
"status": 500,
"body":
{
"msg": "Internal Server Error",
"code": 500,
"ts": 1610167740309
}
调用频率限制
灵动课堂服务端 API 调用频率参见下表:
限制范围 | URI 规则 | 频次限制 | 说明 |
---|---|---|---|
声网账号(非每个 App ID) | /{region}/edu/apps/{appId}/... | 1000 次/秒 | 灵动课堂单区域内所有服务端API共享调用频次限制(不同区域 QPS 限制互相独立)。 |
单个房间 | /{region}/edu/apps/{appId}/../rooms/{roomUuid}/... | 100 次/秒 | 灵动课堂房间相关的接口,单区域相同的
|
单个房间内单个用户 | /{region}/edu/apps/{appId}/../rooms/ {roomUuid}/users/{userUuid}/... | 60次/分 | 灵动课堂房间用户相关的接口,单区域相同的
|
当一个服务端 API 调用超出频率限制时,会返回状态码 429
,表示请求过于频繁。你可以结合业务实际并发需求,参考以下建议,优化 API 调用频率:
- 将 API 请求均匀地分布到各时间窗口。例如,要调用
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}
创建 1000 个房间时,为避免请求超出全局调用上限,你可以每秒创建200 个房间,分 5 秒创建完成。 - 不要在你的客户端直接调用声网的服务端 API,而要在你的应用服务器上调用声网的服务端 RESTful API。例如,在使用设置房间属性接口时,不要在每个学生端同时设置房间属性,可以由学生端请求你的应用服务器,由你的应用服务器定期汇总房间属性后,再调用设置房间属性 API 进行设置。
房间相关
创建课堂
接口描述
课堂创建后,默认保留 5 天。
接口原型
- 方法:POST
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
请求包体参数
参数 | 类型 | 非必填 | 描述 |
---|---|---|---|
roomType | String | 必填 | 房间类型,可设为:
该字段不可更新。 |
roomName | String | 必填 | 房间名称,用于用户显示目的。最长不可超过 64 字符。 |
roomProperties | Object | 非必填 | 房间属性。 |
roomProperties.schedule | Object | 非必填 | 课程计划,包含开始时间,持续时长,拖堂时长等属性。 |
roomProperties.schedule.startTime | Integer | 非必填 | 课堂开始时间戳,单位为毫秒。该字段不可更新。 |
roomProperties.schedule.duration | Integer | 非必填 | 课堂持续时长,单位为秒。如果你设置了课堂持续时长和拖堂时长,当开启录制时,会按照二者之和向上取整设置最长录制时间 maxRecordingHour 参数。详见设置录制状态的 maxRecordingHour 参数说明。 |
roomProperties.schedule.closeDelay | Integer | 非必填 | 拖堂时长,单位为秒。当课堂持续时长结束后,课程会进入“结束”状态(state = 2),此时用户仍可以正常进入和逗留在教室。当拖堂时间结束时,课堂会进入“关闭”状态(state = 3),并踢出所有用户。 |
roomProperties.processes | Object | 非必填 | 申请邀请流程,包含举手等功能。 |
roomProperties.processes.handsUp | Object | 非必填 | 上台设置,包含上台人数上限等。 |
roomProperties.processes.handsUp.maxAccept | Integer | 非必填 | 上台人数上限。 |
roomProperties.processes.handsUp.defaultAcceptRole | String | 非必填 | 默认上台角色,若需要让学生进教室默认上台,则该属性传 "audience" ;若不需要自动上台,该属性传 "" 或不传。 |
roomProperties.flexProps | Object | 非必填 | 初始化房间属性。用户可以根据自己的业务需求为任何教室设置自定义属性。灵活的教室将把这些属性的更改同步到教室中的所有客户端,以实现自己的业务拓展。 详见房间属性最佳实践。 |
roomProperties.widgets | Object | 非必填 | 房间内组件设置。 |
roomProperties.widgets.netlessBoard | Object | 非必填 | 房间内白板组件设置。 |
roomProperties.widgets.netlessBoard.state | Integer | 非必填 | 房间内白板组件状态。可设为:
|
roomProperties.widgets.easemobIM | Object | 非必填 | 房间内聊天室组件设置。 |
roomProperties.widgets.easemobIM.state | Integer | 非必填 | 房间内聊天室组件状态。可设为:
|
roleConfig | Object | 非必填 | 角色配置。 |
roleConfig.2 | Object | 非必填 | 学生角色配置。 |
roleConfig.2.limit | Integer | 非必填 | 学生人数限制。 |
roleConfig.2.defaultStream | Object | 非必填 | 学生默认流配置。如果配置该选项,会按 defaultStream 的设置为第一次进教室的学生创建一条流,流的作用详见基本概念 。本设置仅适用于云课堂场景。 |
roleConfig.2.defaultStream.state | Integer | 非必填 | 学生默认流状态。 可设为:
|
roleConfig.2.defaultStream.videoState | Integer | 非必填 | 学生默认流视频状态。 可设为:
|
roleConfig.2.defaultStream.audioState | Integer | 非必填 | 学生默认流音频状态。 可设为:
|
请求示例
curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"roomName": "test_class",
"roomType": 4,
"roomProperties": {
"schedule": {
"startTime": 1655452800000,
"duration": 600,
"closeDelay": 300
},
"processes": {
"handsUp": {
"maxAccept": 10
}
}
}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
创建云课堂房间
若要使用云课堂,需要先调用服务端接口创建房间,以下是创建云课堂房间的请求示例。
curl -X POST 'https://api.agora.io/{region}/edu/apps/{YourAppId}/v2/rooms/test_room' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"roomName": "test_class", //(Required)
"roomType": 4, // (Required)
"roleConfig": { // (Required) The audio and video permissions of students joining the room are turned on or off by default.
"2": {
"limit": 50,
"defaultStream": {
"state": 1,
"videoState": 1,
"audioState": 1
}
}
},
"roomProperties": {
"schedule": {
"startTime": 1655452800000,
"duration": 600,
"closeDelay": 300
},
"flexProps": { // (Optional) The user's backend can pass customized parameters to the room through this parameter.Users can set custom attributes for any classroom based on their own business needs. Flexible Classroom will synchronize changes in this attribute to all clients in the classroom to realize your own business expansion.
"exampleKey": "exampleValue"
},
"widgets": { // The state of the widgets in the classroom : on or off
"netlessBoard": { // (Required)
"state": 0
},
"easemobIM": {
"state": 1
}
}
}
}'
请求示例
curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"roomName": "test_class",
"roomType": 4,
"roomProperties": {
"schedule": {
"startTime": 1655452800000,
"duration": 600,
"closeDelay": 300
},
"processes": {
"handsUp": {
"maxAccept": 10
}
}
}
}'
查询课堂
接口描述
返回房间对象所有信息。
接口原型
- 方法:GET
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
data | Object | 返回数据,为公共响应参数。包含以下数据:
|
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1684231543281,
"data": {
"roomName": "jasoncai's Room",
"roomUuid": "3579768dd1e1eec8522d3ed76992afd04",
"scenario": "education",
"roleConfig": {
...
},
"roomProperties": {
"reward": {
...
},
"processes": {
"handsUp": {
...
},
"openCamera": {
...
},
"remoteControl": {
...
},
"waveArm": {
...
}
},
"im": {
"huanxin": {
...
}
},
"screen": {
...
},
"groups": {
...
},
"carousel": {
...
},
"widgets": {
"netlessBoard": {
"extra": {
...
},
"state": 1
},
"easemobIM": {
"extra": {
...
}
}
},
"schedule": {
"closeDelay": 600,
"duration": 1800
},
"webhookConfig": {
...
},
"record": {
...
},
"state": 0,
"board": {
"info": {
...
}
},
"roomType": 4
},
"roomTemplate": "edu_medium_v1",
"muteChat": {},
"muteVideo": {},
"muteAudio": {},
"state": 0,
"checkState": false,
"createTime": 1683884683422
}
}
设置课堂状态
接口描述
设置课堂状态。课堂状态可以设置为以下值:
0
: 未开始。1
: 开始。2
: 结束。课堂时间结束,但在拖堂时间内,用户可以加入课堂和在课堂内逗留。3
: 关闭。拖堂时间结束,课堂关闭,所有用户被踢出并无法再进入。
详见灵动课堂有哪些课堂状态?。
接口原型
- 方法:PUT
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/states/{state}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
state | Integer | 必填 | 课堂状态,可以设置为以下值:
|
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/states/1' \
-H 'Authorization: agora token={educationToken}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
"status": 200,
"body":
{
"code": 0,
"msg": "Success",
"ts": 1610450153520
}
更新课堂自定义属性
接口描述
新增或更新指定课堂的自定义属性。
你可以结合自身的业务需求,设置任意课堂自定义属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:PUT
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/properties
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | Object | 必填 | 本次设置的课堂自定义属性。 |
cause | Object | 非必填 | 本次设置原因。 |
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": {
"key1": "value1",
"key2": "value2"
},
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除课堂自定义属性
接口描述
删除指定课堂的自定义属性。
你可以删除任意课堂自定义属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:DELETE
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/properties
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | String[] | 必填 | 本次删除的课堂自定义属性对应的 key。 |
cause | Object | 非必填 | 本次删除原因。 |
请求示例
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": ["key1", "key2"],
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
开启/关闭分组讨论
接口描述
开启或关闭课堂分组讨论功能。
接口原型
- 方法:PUT
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/groups/states/{state}
请求参数
URL 参数
参数 | 类型 | 描述 |
---|---|---|
region | String | (必填)区域。可设为:
|
appId | String | (必填)声网 App ID。 |
roomUUid | String | (必填)课堂 uuid。这是课堂的唯一标识符,也是加入 RTC 和 RTM 的频道名。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
state | Integer | (必填)是否开启分组讨论:
|
请求包体参数
开启分组讨论时需要在请求包体中传入以下参数;关闭分组讨论时不需要传任何参数。
参数 | 类型 | 描述 |
---|---|---|
groups | Array | (必填)待创建的分组列表。包含:
|
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/states/1' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"groups":[
{
"groupUuid": "group1",
"groupName":"Group 01",
"users":[{
"userUuid": "user1"
}]
}
]
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 业务状态码:
|
msg | String | 详细信息。 |
ts | Number | 当前服务端的 Unix 时间戳(毫秒),UTC 时间。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1672989034831
}
用户相关
查询指定用户
接口原型
- 方法:GET
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
userUuid | String | 必填 | 用户 uuid,为公共参数,详见其他业务参数 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user' \
-H 'Authorization: agora token={educationToken}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
data | Object | 返回数据,为公共响应参数。包含以下数据:
|
响应示例
{
"msg":"Success",
"code":0,
"ts":1658126805245,
"data":{
"userName":"jasoncai",
"userUuid":"681d9aca4924e9a84ad301e8cca438a71",
"role":"1",
"userProperties":{},
"updateTime":1658126782174,
"streamUuid":"1417753684",
"state":1
}
}
更新用户自定义属性
接口描述
新增或更新指定用户的自定义属性。
你可以对用户设置任意用户自定义属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:PUT
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}/properties
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
userUuid | String | 必填 | 用户 uuid,为公共参数,详见其他业务参数 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | Object | 必填 | 本次设置的用户自定义属性。 |
cause | Object | 非必填 | 本次设置的原因。 |
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": {
"key1": "value1",
"key2": "value2"
},
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除用户自定义属性
接口描述
删除指定用户的用户自定义属性。
你可以删除用户的任意属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:DELETE
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}/properties
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
userUuid | String | 必填 | 用户 uuid,为公共参数,详见其他业务参数 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | String[] | 必填 | 本次删除的用户自定义属性对应的 key。 |
cause | Object | 非必填 | 本次删除的原因。 |
请求示例
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": ["key1", "key2"],
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
踢人
接口描述
将指定用户从课堂中踢出。成功调用此接口后,服务端会触发一个用户进出课堂事件。你可通过该接口的 dirty
参数设置该用户后续是否还能再加入课堂。
接口原型
- 方法:POST
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}/exit
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
userUuid | String | 必填 | 用户 uuid,为公共参数,详见其他业务参数 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
dirty | Object | 非必填 | 用户踢人标记,包含以下字段:
|
请求示例
curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/exit' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"dirty": {
"state": 1,
"duration": 600
}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
录制相关
设置录制状态
接口描述
开始或结束录制指定课堂。详见课堂录制最佳实践。
接口原型
- 方法:PUT
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/records/states/{state}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
state | Integer | 必填 | 录制状态:
|
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
mode | String | 非必填 | 录制模式:填入 web ,表示启用页面录制模式。录制生成 MP4 文件。此外,录制服务会在当前 MP4 文件时长超过 2 小时或大小超过 2 GB 时创建一个新的 MP4 文件。 |
webRecordConfig | Object | 非必填 | 页面录制配置。当 mode 设为 web 时,你需要通过该参数设置页面录制的详细信息,包含以下字段:
|
retryTimeout | Number | 非必填 | 重试超时时间,单位为秒。灵动课堂RESTful API最多重试两次。设置 retryTimeout 参数后,声网建议你参考课堂录制最佳实践进行操作。 |
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/records/states/1' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"mode": "web",
"webRecordConfig": {
"rootUrl": "https://xxx.yourdomain.com/record_page_prod.html"
},
"retryTimeout": 60
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
data | Object | 返回数据,为公共响应参数。包含以下数据:
|
响应示例
"status": 200,
"body":
{
"code": 0,
"ts": 1610450153520,
"streamingUrl": {
"rtmp": "",
"flv": "",
"hls": ""
}
}
更新录制设置
接口描述
在录制过程中随时调用此接口更新录制相关设置。每次调用此接口都会覆盖原先的设置。
由于录制启动需要一定时间,建议在开启录制至少一分钟后再调用此接口。
接口原型
- 方法:PATCH
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/records/states/1
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
webRecordConfig | Object | 非必填 | 页面录制设置,包含 onhold 属性,必填,Boolean 类型,可设为:
|
请求示例
curl -X PATCH 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/records/states/1' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"webRecordConfig": {
"onhold": false
}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
"status": 200,
"body":
{
"code": 0,
"ts": 1610450153520
}
查询录制列表
接口描述
查询指定课堂内的录制列表。每次开启录制会生成一条记录,你可以通过查询录制列表接口的 nextId
参数分批拉取,每批最多拉取 100 条数据。
- 当类型为页面录制时,单次录制记录可能因为时长或文件大小拆分多个录像 URL,在
recordDetails.url
参数中返回。 - 当类型为单流录制时,每条流的录像会拆分成多个录像 URL,在
recordDetails.url
参数中返回。
接口原型
- 方法:GET
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/records
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
Query 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nextId | String | 非必填 | 下一批数据的起始 ID。第一次查询可传 null,后续查询传入响应结果里得到的 nextId 的值继续查询。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/records' \
-H 'Authorization: agora token={educationToken}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
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
}
}
Widget 相关
删除 Widget
接口描述
删除指定 Widget。
灵动课堂会将这个变化同步到所有端,以此来实现你自己的扩展业务。
接口原型
- 方法:DELETE
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/{widgetUuid}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
widgetUuid | String | 必填 | Widget uuid。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
cause | Object | 非必填 | 本次删除原因。 |
请求示例
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/test_widget' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
设置 Widget 房间属性
设置指定 Widget 的房间属性。
你可以对 Widget 设置任意房间属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性?。
接口原型
- 方法:PUT
- 请求路径:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/{widgetUuid}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
widgetUuid | String | 必填 | Widget uuid。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
extra | Object | 非必填 | Widget 属性。 |
cause | Object | 非必填 | 更新原因。 |
state | Integer | 非必填 | Widget 的活跃状态:
|
ownerUserUuid | String | 非必填 | Widget 所属用户。如果填写了该参数,在 widget 所属用户离线后,widget 会被自动删除。 |
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/test_widget' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": {
"key1": "value1",
"key2": "value2"
},
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除 Widget 房间属性
接口描述
删除指定 Widget 的属性。
你可以删除任意 Widget 属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。设置方式同课堂属性和用户属性,详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:DELETE
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/{widgetUuid}/extra
请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
widgetUuid | String | 必填 | Widget uuid。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | String [] | 必填 | 需删除的 widget 属性数组,即 extra 字段的值。 |
cause | Object | 非必填 | 删除原因。 |
请求示例
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/test_widget/extra' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": ["key-path1", "key-path2"],
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
设置 Widget 用户属性
设置指定 Widget 的用户属性。
你可以对 widget 设置用户属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。设置方式同课堂属性和用户属性,详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:PUT
- 请求路径:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/{widgetUuid}/users/{userUuid}
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
widgetUuid | String | 必填 | Widget uuid。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
userUuid | String | 必填 | 用户 uuid,为公共参数,详见其他业务参数 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | Object | 必填 | 需设置的 Widget 用户属性。 |
cause | Object | 非必填 | 更新原因。 |
请求示例
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/test_widget/users/test_user' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": {
"key1": "value1",
"key2": "value2"
},
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
删除 Widget 用户属性
接口描述
删除指定 Widget 的用户属性。
你可以删除 widget 的用户属性,灵动课堂会将这个属性的变更同步到所有端,以此来实现你自己的扩展业务。设置方式同课堂属性和用户属性,详见如何设置自定义用户属性和课堂属性?
接口原型
- 方法:DELETE
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/{widgetUuid}/users/{userUuid}
请求参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
widgetUuid | String | 必填 | Widget uuid。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
userUuid | String | 必填 | 用户 uuid,为公共参数,详见其他业务参数 |
请求包体参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
properties | String [] | 必填 | 需删除的 Widget 用户属性。 |
cause | Object | 非必填 | 删除原因。 |
请求示例
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/test_widget/users/test_user' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
"properties": ["key1","key2"],
"cause": {}
}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610167740309
}
事件同步
查询所有课堂事件
接口描述
在服务端查询指定 App ID 下所有课堂中发生的事件。
你可定时轮询该接口来监听灵动课堂中发生的事件。
- 同一个事件只会返回一次,即第二次查询时不会返回该事件。
- 最早可查一小时内未销毁的课堂里的事件。
接口原型
- 方法:GET
- 接入点:
/{region}/edu/polling/apps/{appId}/v2/rooms/sequences
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/polling/apps/{yourAppId}/v2/rooms/sequences' \
-H 'Authorization: agora token={educationToken}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
data | Object | 返回数据,为公共响应参数 。包含以下数据: |
响应示例
"status": 200,
"body":
{
"msg": "Success",
"code": 0,
"ts": 1610167740309,
"data":[
{
"roomUuid": "xxxxxx",
"cmd": 20,
"sequence": 1,
"version": 1,
"data":{}
}
]
}
查询指定类型事件
接口描述
查询指定课堂内指定类型的事件。
你可以通过 nextId
分批查询,每批最多查询 100 条数据。
- 同一事件可重复查询。
- 仅能查询未销毁课堂内的事件。默认情况下,课堂会在结束后一小时销毁。
接口原型
- 方法:GET
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/sequences
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
Query 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nextId | String | 非必填 | 下一批数据的起始 ID。第一次查询可传 null,后续查询传入响应结果里得到的 nextId 的值。 |
cmd | Integer | 非必填 | 事件类型,详见事件枚举。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/sequences?cmd=20' \
-H 'Authorization: agora token={educationToken}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
data | Object | 返回数据,为公共响应参数。包含以下数据:
|
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610433913533,
"data": {
"total": 1,
"list": [
{
"roomUuid": "",
"cmd": 20,
"sequence": 1,
"version": 1,
"data": {}
}
],
"nextId": null,
"count": 1
}
}
查询指定 Widget 事件
接口描述
查询指定课堂内指定 Widget 的相关事件。
你可以通过 nextId
分批查询,每批最多查询 100 条数据。
- 同一事件可重复查询。
- 仅能查询未销毁课堂内的事件。默认情况下,课堂会在结束后一小时销毁。
接口原型
- 方法:GET
- 接入点:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/{widgetUuid}/sequences
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
widgetUuid | String | 必填 | Widget uuid。长度在 64 字符以内。 以下为支持的字符集范围(共 89 个字符):
|
Query 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nextId | String | 非必填 | 下一批数据的起始 ID。第一次查询可传 null,后续查询传入响应结果里得到的 nextId 的值。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/test_widget/sequences' \
-H 'Authorization: agora token={educationToken}'
响应参数
参数 | 类型 | 描述 |
---|---|---|
code | Integer | 响应状态码,详见公共响应参数。 |
msg | String | 接口响应文字信息,详见公共响应参数。 |
ts | Number | 当前服务端的 Unix 时间戳,详见公共响应参数。 |
data | Object | 返回数据,为公共响应参数 。包含以下数据:
|
响应示例
{
"msg": "Success",
"code": 0,
"ts": 1610433913533,
"data": {
"total": 1,
"list": [
{
"roomUuid": "",
"cmd": 1110,
"sequence": 1,
"version": 1,
"data": {
"action": 1,
"widgetUuid": "test_widget",
"changeProperties": {
"extra": {},
"state": 1
}
},
"fromUser": {
"userUuid": "userUuid1",
"userName": "userName1",
"role": 1
},
"operator": {
"userUuid": "userUuid1",
"userName": "userName1",
"role": 1
}
}
],
"nextId": null,
"count": 1
}
}
查询答题器事件
接口原型
- 方法:GET
- 请求路径:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/popupQuiz/sequences
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
Query 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nextId | String | 非必填 | 下一批数据的起始 ID。第一次查询可传 null,后续查询传入响应结果里得到的 nextId 的值。 |
count | Integer | 非必填 | 本批数据条数,默认值为 100。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/popupQuiz/sequences' \
-H 'Authorization: agora token={educationToken}'
响应参数
不同情况下 data
中返回的字段不同,具体如下:
-
老师开启答题后,答题器的汇总数据会发生变化,
data
中包含以下字段:字段 类型 说明 action Integer 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.extra Object 属性补充信息 changeProperties.extra.correctItems Object[] 正确选项 changeProperties.extra.correctCount Integer 本题答对人数 changeProperties.extra.answerState Integer 本次答题状态: 1
: 答题进行中0
: 答题结束
changeProperties.extra.receiveQuestionTime Long 收到题目时间 changeProperties.extra.popupQuizId String 题目 ID changeProperties.extra.averageAccuracy Float 本题正确率 changeProperties.extra.totalCount Integer 本题回答总人数 changeProperties.extra.items Object[] 本题的所有选项 changeProperties.state Integer 答题器状态: 0
: 非活跃1
: 活跃
cause Object 属性变更原由。 cause.popQuizId String 答题器 ID。 cause.action Integer 操作类型: 1
: 老师开始答题。2
: 老师结束答题。3
: 学生提交答案。4
: 汇总信息同步。
operator Object 操作人 operator.userUuid String 用户 ID operator.userName String 用户名称 operator.role String 用户角色 -
学生提交答案后,该学生的答题数据会发生变化,
data
中包含以下字段:字段 类型 说明 action Integer 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.lastCommitTime Long 最后一次提交时间 changeProperties.popupQuizId String 题目 ID changeProperties.selectedItems Object[] 该学生提交的答案 changeProperties.isCorrect Boolean 该学生提交的答案是否正确 cause Object 属性变更原由。 cause.popQuizId String 答题器 ID。 cause.action Integer 操作类型: 1
: 老师开始答题。2
: 老师结束答题。3
: 学生提交答案。4
: 汇总信息同步。
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 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.extra Object 属性补充信息 changeProperties.extra.selectedCount Integer 已经答题人数 changeProperties.extra.correctCount Integer 本题答对人数 changeProperties.extra.averageAccuracy Float 本题正确率 changeProperties.extra.totalCount Integer 本题回答总人数 cause Object 属性变更原由。 cause.popQuizId String 答题器 ID。 cause.action Integer 操作类型: 1
: 老师开始答题。2
: 老师结束答题。3
: 学生提交答案。4
: 汇总信息同步。
operator Object 操作人 operator.userUuid String 用户 ID operator.userName String 用户名称 operator.role String 用户角色 -
老师结束答题后,答题器的汇总数据会发生变化,
data
中包含以下字段:字段 类型 说明 action Integer 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.extra Object 属性补充信息 changeProperties.extra.selectedCount Integer 已经答题人数 changeProperties.extra.correctCount Integer 本题答对人数 changeProperties.extra.answerState Integer 本次答题状态: 1
: 答题进行中0
: 答题结束
changeProperties.extra.averageAccuracy Float 本题正确率 changeProperties.extra.totalCount Integer 本题回答总人数 cause Object 属性变更原由。 cause.popQuizId String 答题器 ID。 cause.action Integer 操作类型: 1
: 老师开始答题。2
: 老师结束答题。3
: 学生提交答案。4
: 汇总信息同步。
operator Object 操作人 operator.userUuid String 用户 uuid operator.userName String 用户名称 operator.role String 用户角色
响应示例
-
老师开启答题后,答题器的汇总数据发生变化:
JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"extra.correctItems": [
"A",
"B",
"D"
],
"extra.totalCount": NumberInt("1"),
"extra.answerState": NumberInt("1"),
"state": NumberInt("1"),
"extra.popupQuizId": "ab5b183238a74d5a9c955dc87c6397e0",
"extra.averageAccuracy": 0,
"extra.correctCount": NumberInt("0"),
"extra.items": [
"A",
"C",
"B"
],
"extra.receiveQuestionTime": NumberLong("1652413962895")
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
} -
学生提交答案后,该学生的答题数据发生变化:
JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"selectedItems": [
"A",
"B",
"D"
],
"isCorrect": true,
"popupQuizId": "ab5b183238a74d5a9c955dc87c6397e0",
"lastCommitTime": NumberLong("1652413989997")
},
"fromUser": {
"userName": "yerongzhe2",
"userUuid": "yerongzhe22",
"role": "audience"
} -
老师结束答题后,答题器的汇总数据发生变化:
JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"extra.totalCount": NumberInt("1"),
"extra.answerState": NumberInt("0"),
"extra.selectedCount": NumberInt("1"),
"extra.averageAccuracy": 1,
"extra.correctCount": NumberInt("1")
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
}
查询投票器事件
接口原型
- 方法:GET
- 请求路径:
/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/widgets/poll/sequences
请求参数
URL 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
region | String | 必填 | 服务区域,为公共参数,详见区域。 |
appId | String | 必填 | 声网 App ID,为公共参数,详见其他业务参数。 |
roomUuid | String | 必填 | 课堂 uuid,为公共参数,详见其他业务参数。 |
Query 参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
nextId | String | 非必填 | 下一批数据的起始 ID。第一次查询可传 null,后续查询传入响应结果里得到的 nextId 。 |
count | Integer | 非必填 | 本批数据条数,默认值为 100。 |
请求示例
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/widgets/popupQuiz/sequences' \
-H 'Authorization: agora token={educationToken}'
响应参数
不同情况下 data
中返回的字段不同,具体如下:
-
老师开启投票后,投票器的汇总数据会发生变化,
data
中包含以下字段:字段 类型 说明 action Integer 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.extra Object 属性补充信息 changeProperties.extra.mode Integer 投票模式: 1
: 单选2
: 多选
changeProperties.extra.pollingState Integer 本次投票状态: 1
: 投票进行中0
: 投票结束
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 投票器状态: 0
: 非活跃1
: 活跃
cause Object 属性变更原由。 cause.pollId String 投票器 ID。 cause.action Integer 操作类型: 1
: 老师开始投票。2
: 老师结束投票。3
: 学生提交投票。4
: 汇总信息同步。
operator Object 操作人 operator.userUuid String 用户 ID operator.userName String 用户名称 operator.role String 用户角色 -
学生提交选项后,该学生的投票数据会发生变化,
data
中包含以下字段:字段 类型 说明 action Integer 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.extra Object 属性补充信息 changeProperties.extra.pollId String 本次投票 ID changeProperties.extra.selectIndex Object[] 该学生选择的选项的索引 cause Object 属性变更原由。 cause.pollId String 投票器 ID。 cause.action Integer 操作类型: 1
: 老师开始投票。2
: 老师结束投票。3
: 学生提交投票。4
: 汇总信息同步。
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 操作类型 widgetUuid String Widget ID 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 Object 属性变更原由。 cause.pollId String 投票器 ID。 cause.action Integer 操作类型: 1
: 老师开始投票。2
: 老师结束投票。3
: 学生提交投票。4
: 汇总信息同步。
operator Object 操作人 operator.userUuid String 用户 ID operator.userName String 用户名称 operator.role String 用户角色 -
老师结束投票后,投票器的汇总数据会发生变化,
data
中包含以下字段:字段 类型 说明 action Integer 操作类型 widgetUuid String Widget ID changeProperties Object 发生变更的属性 changeProperties.extra Object 属性补充信息 changeProperties.extra.pollingState Integer 本次投票状态: 1
: 投票进行中0
: 投票结束
changeProperties.extra.pollDetails Map<String, Object>
投票详情, key
为选项索引,从0
开始。changeProperties.extra.pollDetails.num Integer 选择该选项的人数 changeProperties.extra.pollDetails.percentage Float 选择该选项的人数所占百分比 changeProperties.extra.pollId String 本次投票 ID cause Object 属性变更原由。 cause.pollId String 投票器 ID。 cause.action Integer 操作类型: 1
: 老师开始投票。2
: 老师结束投票。3
: 学生提交投票。4
: 汇总信息同步。
operator Object 操作人 operator.userUuid String 用户 ID operator.userName String 用户名称 operator.role String 用户角色
响应示例
-
老师开启投票后,投票器的汇总数据发生变化:
JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"extra.pollState": NumberInt("1"),
"extra.pollItems": [
"aaa",
"bbb",
"ccc",
"ddd",
"eee"
],
"extra.mode": NumberInt("2"),
"state": NumberInt("1"),
"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"
} -
学生提交选项后,该学生的投票数据发生变化:
JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"selectIndex": [
NumberInt("1"),
NumberInt("2"),
NumberInt("4")
]
},
"fromUser": {
"userName": "yerongzhe2",
"userUuid": "yerongzhe22",
"role": "audience"
},
"operator": {
"userName": "server",
"userUuid": "server",
"role": "server"
} -
学生提交选项后,投票器的汇总数据发生变化:
JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"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
中包含以下字段:JSON"action": NumberInt("1"),
"widgetUuid": "xxxxxxxxx",
"changeProperties": {
"extra.pollId": "e556ce3df5cd4c23941b03bf54d29ba3",
"extra.pollState": NumberInt("0"),
"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 | 可能的原因:
|
403 | 30403200 | 课堂已禁言,无法发送聊天消息。 |
404 | N/A | 服务器无法找到请求的资源。 |
404 | 20404100 | 课堂不存在。 |
404 | 20404200 | 用户不存在。 |
410 | 30410100 | 课堂已结束。 |
409 | 30409410 | 录制状态冲突,录制未开始。 |
409 | 30409411 | 录制状态冲突,录制未结束。 |
400 | 30400412 | 参数 rootUrl 不能为空。 |
409 | 30409100 | 课程状态冲突,课程已开始。 |
409 | 30409101 | 课程状态冲突,课程已结束。 |
400 | 30400100 | 租户 ID 不能为空。 |
429 | N/A | 接口被限流。 |
500 | 500 | 服务器内部错误,无法完成请求。 |
503 | N/A | 服务器内部错误,充当网关或代理的服务器未从远端服务器获取响应。 |
事件枚举
本页列出通过灵动课堂 RESTful API 查询所有课堂事件获取到的所有事件类型。
课堂状态变更
cmd
为 1
时,该事件提示课堂状态发生变更,data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
state | Integer | 当前课堂状态:
|
startTime | Number | 课堂开始时间,Unix 时间戳(毫秒),UTC 时间。当state=1时,此字段有值。 |
endTime | Number | 课堂结束时间,Unix 时间戳(毫秒),UTC 时间。当state=2时,此字段有值。 |
closeTime | Number | 课堂关闭时间,Unix 时间戳(毫秒),UTC 时间。当state=3时,此字段有值。 |
示例
{
"startTime":1611561776588,
"state":1
}
用户进出课堂
cmd
为 20
时,该事件提示有用户进出课堂。data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
total | Integer | 进入和退出课堂的用户总数。 |
onlineUsers | Object 数组 | 进入课堂的用户,包含以下字段:
|
offlineUsers | Object 数组 | 退出课堂的用户,包含以下字段:
|
示例
{
"total":3,
"onlineUsers":[
{
"userName":"",
"userUuid":"",
"role":"0",
"userProperties":{ },
"streamUuid":"",
"type":1,
"updateTime":1611561776588
}
],
"offlineUsers":[
{
"userName":"",
"userUuid":"",
"role":"0",
"userProperties":{},
"streamUuid":"",
"type":1,
"updateTime":1611561776588
}
]
}
录制状态变更
cmd
为 1001
时,该事件提示录制状态发生变更,data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
recordId | String | 一次录制的的唯一标识符。调用设置录制状态 API 开始录制然后结束录制视为一次录制。仅当 state 为 1 时有此字段。 |
sid | String | 声网云端录制服务的 sid 。仅当 state 为 1 时有此字段。 |
resourceId | String | 声网云端录制服务的 resourceId 。仅当 state 为 1 时有此字段。 |
state | Integer | 当前录制状态:
|
startTime | Number | 录制开始时间,Unix 时间戳(毫秒),UTC 时间。录制开始后此字段有值。 |
endTime | Number | 录制结束时间,Unix 时间戳(毫秒),UTC 时间。录制结束后此字段有值。 |
streamingUrl | Object | 经由页面录制后推到 CDN 的流地址。学生可以通过该地址观看教学。 |
retryTimes | Integer | 当前重试次数。 |
ready | Boolean | 录制页面是否加载完成,值为 true 时有此字段。 |
onhold | Boolean | 是否在启动页面录制任务时暂停页面录制。
|
示例
{
"recordId":"xxx",
"sid":"xxx",
"resourceId":"xxx",
"state":1,
"startTime":1611564500488,
"streamingUrl": {
"rtmp": "",
"flv": "",
"hls": ""
}
}
录像文件上传
cmd
为 1002
时,该事件提示录制文件上传成功,data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
recordId | String | 一次录制的的唯一标识符。调用设置录制状态 API 开始录制然后结束录制视为一次录制。仅当 state 为 1 时有此字段。 |
addUrl | String | 本次新增的录像地址。 |
recordDetails | String | JSONArray 类型。包含所有录制文件列表,包含以下字段:
|
allUploaded | Boolean | 所有文件都上传完成时,该字段为 true ,否则该字段为 null 。 |
示例
{
"recordId": "xxx",
"addUrl": "https://xxxx.com/xxx.mp4",
"recordDetails": [{
"url": "https://xxxx.com/xxx.mp4"
}],
"allUploaded": true
}
奖励数量变更
cmd
为 1101
时,该事件提示奖励数量发生变更,data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
rewardDetails | Object 数组 | 一个 Object 代表一个用户的奖励数量变更情况,包含以下字段:
|
updateTime | Number | 奖励变更时间,Unix 时间戳(毫秒),UTC 时间。 |
示例:
{
"rewardDetails":[ {
"userUuid":"",
"changedReward": 1,
"totalReward": 10
} ],
"updateTime":1611564500488
}
讲台人员变更
cmd
为 1501
时,该事件提示讲台人员发生变化,data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
acceptedUsers | Object 数组 | 当前台上人员列表,包含以下字段:
|
addAcceptedUsers | Object 数组 | 本次上台人员列表,包含以下字段:
|
removeAcceptedUsers | Object 数组 | 本次下台人员列表,包含以下字段:
|
示例:
{
"acceptedUsers": [{
"userUuid":""
}],
"addAcceptedUsers": [{
"userUuid":""
}],
"removeAcceptedUsers": [{
"userUuid":""
}]
}
挥手人员变更
cmd
为 1502
时,该事件提示挥手人员发生变更,data
中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
progressUsers | Object 数组 | 当前举手人员列表,包含以下字段:
|
addProgressUsers | Object 数组 | 本次新增举手人员列表,包含以下字段:
|
removeProgressUsers | Object 数组 | 本次移除举手人员列表,包含以下字段:
|
示例:
{
"progressUsers": [{
"userUuid":"",
"payload":{}
}],
"addProgressUsers": [{
"userUuid":"",
"payload": {}
}],
"removeProgressUsers": [{
"userUuid":"",
"payload": {}
}]
}