如何调用 API
本文介绍灵动课堂 RESTful API 的构成，并引导你如何正确地调用 API。
前提条件
在调用 RESTful API 之前，请确保已获取声网 App ID 和 Token（可选，用于安全鉴权）；对于服务端产品，还需要获取客户 ID 和客户密钥。可参考开通服务。
配置 URL
以创建课堂 API 为例，请求的 URL 示例如下：
https://api.sd-rtn.com/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}
其中：
https：通信协议。声网使用 HTTPS 协议。api.sd-rtn.com：声网服务端域名。{region}/edu/apps/{appId}/v2/rooms/{roomUuid}：资源路径。{region}：请求的目标区域，如中国大陆为cn。{appId}：声网为每个开发者提供的 App ID，是项目的唯一标识。{roomUuid}：课堂 UUID，是课堂的唯一标识。
以上示例仅作参考，你可以参照要调用的 API 的文档，在代码源文件或调试应用中先选择调用方法（如 GET、POST、PUT、PATCH、DELETE），然后根据 API 文档来配置实际的请求 URL。请求 URL 需要区分大小写。
发送请求
请求包括请求 Header 和请求 Body 两部分。在配置完 URL 后，你需要设置请求 Header 和 Body 信息，然后向服务器发送请求。
以下是创建课堂的请求示例：
curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/{roomUuid}' \
-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
}
}
}
}'
以上示例仅作参考。你可以参照要调用的 API 的文档，配置实际的请求 Header 和 Body 信息。
请求 Header
请求 Header 包含了处理请求所需要的信息，比如：
Content-Type：指定请求 Body 的类型为application/json，以UTF-8字符编码进行编码。Authorization：声网 RESTful API 要求 HTTP Token 认证。每次发送 HTTP 请求时，都必须在请求 Header 中填入Authorization字段。关于如何生成该字段的值，请参考实现 HTTP Token 认证。
请求 Body（可选）
请求 Body 包含了要发送给服务器的数据。例如，创建一个课堂，你需要在请求 Body 中包含课堂的参数信息，如课堂名称、课堂类型、课堂开始时间、持续时间、拖堂时长等。详情可参考具体 API 文档的参数描述。请求 Body 需要区分大小写。
接收响应
在发起请求后，声网服务器会对你的请求进行响应。响应包括响应状态码、响应 Header 和响应 Body。
响应状态码
响应的 HTTP 状态码分 200 和非 200 两种情况，详情可参考响应状态码。
- 如果 HTTP 状态码为
200，表示请求成功。 - 如果 HTTP 状态码不为
200，参考响应状态码排查问题。
响应 Header（可选）
响应 Header 指明了响应的标识，以区分不同请求所收到的响应。
响应 Body
响应 Body 包含了服务器反馈的数据。例如，查询课堂的响应 Body 包括标识课堂房间的 UUID、课堂名称、创建时间、房间属性等信息。具体以每个 API 的响应为准。
以下是查询课堂的响应示例：
{
"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
}
}