如何调用 API

本文介绍灵动课堂 RESTful API 的构成，并引导你如何正确地调用 API。

前提条件

在调用 RESTful API 之前，请确保已获取声网 App ID 和 Token（可选，用于安全鉴权）；对于服务端产品，还需要获取客户 ID 和客户密钥。可参考开通服务。

配置 URL

以创建课堂 API 为例，请求的 URL 示例如下：

HTTP

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 需要区分大小写。

发送请求

请求包括请求头和请求包体两部分。在配置完 URL 后，你需要设置请求头和包体信息，然后向服务器发送请求。

以下是创建课堂的请求示例：

Shell

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 的文档，配置实际的请求头和包体信息。

请求头

请求头包含了处理请求所需要的信息，比如：

• Content-Type：指定请求体的类型为 application/json，以 UTF-8 字符编码进行编码。
• Authorization：声网 RESTful API 要求 HTTP Token 认证。每次发送 HTTP 请求时，都必须在请求头中填入 Authorization 字段。关于如何生成该字段的值，请参考实现 HTTP Token 认证。

请求包体（可选）

请求包体包含了要发送给服务器的数据。例如，创建一个课堂，你需要在请求包体中包含课堂的参数信息，如课堂名称、课堂类型、课堂开始时间、持续时间、拖堂时长等。详情可参考具体 API 文档的参数描述。请求包体需要区分大小写。

接收响应

在发起请求后，声网服务器会对你的请求进行相应。响应包括响应状态码、响应头和响应包体。

响应状态码

响应的 HTTP 状态码分 200 和非 200 两种情况，详情可参考响应状态码。

• 如果 HTTP 状态码为 200，表示请求成功。
• 如果 HTTP 状态码不为 200，参考响应状态码排查问题。

响应头（可选）

响应头指明了响应的标识，以区分不同请求所收到的的响应。

响应包体

响应包体包含了服务器反馈的数据。例如，查询课堂的响应包体包括标识课堂房间的 UUID、课堂名称、创建时间、房间属性等信息。具体以每个 API 的响应为准。

以下是查询课堂的响应示例：

JSON

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

错误处理

当你遇到问题时，可以使用开发者工具查看请求和响应，结合响应状态码进行排查。如未能解决问题，可联系技术支持。