如何调用 API

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

前提条件

在调用 RESTful API 之前，确保已经开通服务并获取 App ID 和临时 Token。

配置 URL

以创建会议 API 为例，请求的 URL 示例如下：

HTTP

https://api.sd-rtn.com/{region}/conference/apps/{appId}/v1/rooms/{roomUuid}

其中：

• https：通信协议。声网使用 HTTPS 协议。
• api.sd-rtn.com：声网服务端域名。详见保障 REST 服务高可用。
• {region}/conference/apps/{appId}/v1/rooms/{roomUuid}：资源路径。
  • {region}：请求的目标区域，目前仅支持 cn，代表中国大陆。
  • {appId}：声网为每个开发者提供的 App ID，是项目的唯一标识。
  • {roomUuid}：UUID（通用唯一识别码），标识每个会议房间。

以上示例仅作参考，你可以参照要调用的 API 的文档，在代码源文件或调试应用中先选择调用方法（如 GET、POST、PUT、PATCH、DELETE），然后根据 API 文档来配置实际的请求 URL。请求 URL 需要区分大小写。

发送请求

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

以下是创建会议的请求示例：

Shell

curl -X POST 'https://api.sd-rtn.com/{region}/conference/apps/{yourAppId}/v1/rooms/{roomUuid}' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={apaasToken}' \
--data-raw '{
    "roomName": "test_conference",
    "roomTemplate": "conf_finity_v1",
    "roomProperties": {
        "schedule": {
            "startTime": 1655452800000,
            "duration": 600,
            "closeDelay": 300
        }
    }
}'

示例仅作参考。你可以参照要调用的 API 的文档，配置实际的请求 Header 和 Body 信息。

请求 Header

请求 Header 包含了处理请求所需要的信息：

• Content-Type：application/json。代表指定请求 Body 的类型为 JSON，以 UTF-8 字符编码进行编码。

• Authorization：用于 HTTP Token 认证的鉴权字段。每次发送 HTTP 请求时，都必须填入 Authorization 字段。详见实现 HTTP Token 认证。

请求 Body（可选）

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

接收响应

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

响应状态码

响应的 HTTP 状态码分 200 和非 200 两种情况：

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

响应 Header（可选）

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

响应 Body

响应 Body 包含了服务器反馈的数据。

以下是通用的响应示例：

JSON

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

错误处理

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