调用互动白板 RESTful API

前提条件Copy Anchor Link

本文介绍互动白板 RESTful API 的构成，并引导你如何正确地调用 API。

在调用 RESTful API 之前，你需要参考开启和配置互动白板服务完成以下准备工作：

• 创建一个开启了互动白板服务的声网项目。
• 获取访问密钥 Access Key (AK) 和私有访问密钥 Secret Access Key (SK)。
• 如需调用文档转换和截图服务端 API，确保已在控制台开启对应服务。

配置 URLCopy Anchor Link

以生成 SDK Token的请求 URL 示例如下：

https://api.netless.link/v5/tokens/teams

其中：

• https：通信协议。声网使用 HTTPS 协议。

• api.netless.link：互动白板服务端域名。

• v5/tokens/teams：资源路径。

  • v1/projects：API 版本和资源名。
  • teams：指定调用的接口，此处为生成 SDK Token 的接口。

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

发送请求Copy Anchor Link

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

以下是发起文档转换的请求示例：

curl --request POST \
  --url https://api.netless.link/v5/projector/tasks \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'region: cn-hz' \
  --header 'token: NETLESSSDK_XXXXXXXXXXXXXXXX' \
  --data '{
  "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
  "type": "dynamic",
  "preview": true,
  "webhookEndpoint": "https://example.com/agoracallback",
  "webhookRetry": 3,
  "imageCompressionLevel": 0
}'

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

请求 HeaderCopy Anchor Link

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

• Accept：告知服务器，客户端可以处理哪些类型的响应，如 application/json。
• Content-Type：指定请求体的类型为 application/json。
• X-Request-ID：本次请求的 UUID（通用唯一识别码）。

请求 Body（可选）Copy Anchor Link

请求 Body 包含了要发送给服务器的数据。例如，发起一个文档转换任务，你需要在请求 Body 中包含待转换的源文件 URL、转换任务类型、是否需要生成预览图等。详情可参考具体 API 文档的参数描述。请求 Body 需要区分大小写。

接收响应Copy Anchor Link

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

响应状态码Copy Anchor Link

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

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

响应 Header（可选）Copy Anchor Link

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

• X-Request-ID，本次请求的 UUID（通用唯一识别码）。

响应 BodyCopy Anchor Link

响应 Body 包含了服务器返回的数据。例如，查询转换任务进度的响应 Body 包含转换任务的 UUID、状态、类型、进度百分比等信息。具体信息以每个 API 的返回值为准。

以下是查询转换任务进度的响应示例：

{
  "uuid": "2fdxxxx7e",
  "status": "Finished",
  "type": "dynamic",
  "convertedPercentage": 100,
  "prefix": "https://xxxx.com/dynamicConvert",
  "pageCount": 10,
  "previews": {
    "1": "https://xxxx.xx.xx/1.png",
    "2": "https://xxxx.xx.xx/2.png"
  },
  "note": "https://xxx.xx.xx/note.json",
  "images": {
    "1": {
      "width": 720,
      "height": 1080,
      "url": "https://xxxx.xx.xx/1.xxx"
    },
    "2": {
      "width": 720,
      "height": 1080,
      "url": "https://xxxx.xx.xx/2.xxx"
    }
  },
  "errorCode": "20xxxxx",
  "errorMessage": "xxx"
}

错误处理Copy Anchor Link

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