灵动课堂云服务 RESTful API

本文介绍灵动课堂云服务 RESTful API 的详细信息。

基本信息

域名

所有请求都发送给域名：api.agora.io。

数据格式

所有请求的 Content-Type 类型为 application/json。

认证方式

灵动课堂云服务 RESTful API 支持 Token 认证。你需要在发送 HTTP 请求时在 HTTP 请求头部的 x-agora-token 字段和 x-agora-uid 字段分别填入：

• 服务端生成的 RTM Token。
• 生成 RTM Token 时使用的 uid。

具体生成 RTM Token 的方法请参考生成 RTM Token 文档。

设置课堂状态

接口描述

设置课堂状态（未开始/开始/结束）。课堂状态说明详见课堂状态管理文档。

接口原型

• 方法：PUT
• 接入点：/edu/apps/{appId}/v2/rooms/{roomUUid}/states/{state}

请求参数

URL 参数

需要在 URL 中传入以下参数。

请求示例

// 设置 test_class 的课堂状态为开始
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/states/1

响应参数

响应示例

"status": 200,
"body":
{
  "code": 0,
  "msg": "Success",
  "ts": 1610450153520
}

踢人

接口描述

将指定用户从课堂中踢出。成功调用此接口后，服务端会触发一个用户进出课堂事件。你可通过 dirty 参数设置该用户后续是否还能再加入课堂。

接口原型

• 方法：POST
• 接入点：/edu/apps/{appId}/v2/rooms/{roomUUid}/users/{userUuid}/exit

请求参数

URL 参数

在 URL 中传入以下参数。

请求包体参数

在请求包体中传入以下参数。

请求示例

请求 URL

// 将 ID 为 123 的用户从 test_class 里踢出
https://api.agora.io/edu/apps/{your_app_Id}/v2/rooms/test_class/users/123/exit

请求包体

{
    "dirty": {
        "state": 1,
        "duration": 600
    }
}

响应参数

响应示例

{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

设置录制状态

接口描述

开始或结束录制指定课堂。

接口原型

• 方法：PUT
• 接入点：/edu/apps/{appId}/v2/rooms/{roomUUid}/records/states/{state}

请求参数

URL 参数

需要在 URL 中传入以下参数。

请求包体参数

在请求包体中传入以下参数。

请求示例

请求 URL

// 开始录制名称为 test_class 的课堂
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}"
    }
}

响应参数

响应示例

"status": 200,
"body":
{
  "code": 0,
  "ts": 1610450153520
}

获取录制列表

接口描述

获取指定课堂内的录制列表。

你可以通过 nextId 分批拉取，每批最多拉取 100 条数据。

接口原型

• 方法：GET
• 接入点：/edu/apps/{appId}/v2/rooms/{roomUuid}/records

请求参数

URL 参数

需要在 URL 中传入以下参数。

Query 参数

请求示例

// 获取 test_class 里的录制列表
https://api.agora.io/edu/apps/{yourappId}/v2/rooms/test_class/records?nextId=xxx

响应参数

响应示例

"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
}

上传公共资源

接口描述

在指定课堂内上传一个公共资源。课堂内的所有用户都可以看到该课堂的公共资源。

接口原型

• 方法：PUT
• 接入点：/edu/apps/{appId}/v1/rooms/{roomUuid}/resources/{resourceUuid}

请求参数

URL 参数

在 URL 中传入以下参数。

请求包体参数

在请求包体中传入以下参数。

请求示例

请求 URL

// 在 test_class 里上传一个 ID 为 class_file_1 的公共资源
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": ""
    },
}

响应参数

响应示例

{
    "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"
        }
    }
}

删除公共资源

接口描述

删除指定课堂内的一个或多个公共资源。

接口原型

• 方法：DELETE
• 接入点：/edu/apps/{appId}/v1/rooms/{roomUuid}/resources

请求参数

URL 参数

在 URL 中传入以下参数。

请求包体参数

在请求包体中传入以下参数。

请求示例

请求 URL

https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources

请求包体

{
    "resourceUuids": ["uuid1","uuid2"]
}

响应参数

响应示例

{
    "msg":"Success",
    "code":0,
    "ts":1610433913533
}

获取公共资源

接口描述

获取指定课堂内的所有公共资源。

接口原型

• 方法：GET
• 接入点：/edu/apps/{appId}/v1/rooms/{roomUuid}/resources

请求参数

URL 参数

在 URL 中传入以下参数。

请求示例

请求 URL

// 获取 test_class 里 ID 为 class_file_1 的公共资源
https://api.agora.io/edu/apps/{your_app_Id}/v1/rooms/test_class/resources

响应参数

响应示例

{
    "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 条数据。

// 获取 test_class 里的课堂状态变更事件
https://api.agora.io/edu/apps/{appId}/v2/rooms/test_class/sequences?nextId=50&cmd=1

{
    "msg":"Success",
    "code":0,
    "ts":1610433913533,
    "data":{
        "total":1,
        "list":[
            {
                "roomUuid": "",
                "cmd": 20,
                "sequence": 1,
                "version": 1,
                "data":{}
            }
        ],
        "nextId": null,
        "count":1
    }
}

https://api.agora.io/edu/polling/apps/{yourappId}/v2/rooms/sequences

"status": 200,
"body":
{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309,
    "data":[
        {
            "roomUuid": "xxxxxx",
            "cmd": 20,
            "sequence": 1,
            "version": 1,
            "data":{}
        }
    ]
}

{
    "properties" :{
        "key1":"value1",
        "key2":"value2"
    },
    "cause":{}
}

{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

{
    "properties" :[
        "key1",
        "key2"
    ],
    "cause":{}
}

{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

{
    "properties" :{
        "key1":"value1",
        "key2":"value2"
    },
    "cause":{}
}

{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}

{
    "properties" :[
        "key1",
        "key2"
    ],
    "cause":{}
}

{
    "msg": "Success",
    "code": 0,
    "ts": 1610167740309
}