REST 集成指南

更新时间 2025/01/04 10:00:24

欢迎使用我们的 REST API 来为您的应用增加更多功能。本指南将带您了解如何正确调用 API 接口，并处理来自服务端的响应。

重要声明:
如果您先前已经集成了旧版画布 REST 服务，并希望查看相关文档，请移步此处。我们强烈建议您尽早迁移到我们全新的 REST API 以获得更好的 API 体验与服务支持，详情请参考新版 REST 介绍。

Access Token

为了确保 API 请求的安全性，我们使用 Access Token 作为调用接口的凭证。一个有效的 Access Token 可以标识和验证请求者的身份，并允许其进行相应的 API 调用。

请注意，本文描述的 Access Token 仅适用于英飞 REST 服务鉴权机制，与画布 WebSDK 初始化 Token，及画布辅助 SDK 鉴权 Token 在使用场景及生成方式上均有不同，请注意区分并避免混用。

获取 Access Token

要获取 Access Token，请按照以下流程操作：

访问我们的开发者控制台。
注册并登录您的账号，创建一个新应用或选择一个已有的应用。
获取您的应用凭据 appId 与 appSecret。

上述详细流程可以参考新人指引文档。通过应用凭据，您可以调用我们的 REST API 来申请 Access Token，请求示例如下：

curl https://developer.infi.cn/infi/api/v1/auth/tokens \
     -H 'Content-Type: application/json' \
     --data '{"appId": "YOUR_APP_ID","appSecret": "YOUR_APP_SECRET"}'

注意：请确保将示例中 YOUR_APP_ID 与 YOUR_APP_SECRET 替换为您的应用凭据值。

请求成功后，您将收到一个包含 Access Tokens 的 JSON 响应:

{
  "accessToken": "YOUR_ACCESS_TOKEN",
  "expiresIn": 60000
}

注意：

如需获取更多接口信息，例如参数、返回详解，您可以查阅认证章节文档。

请保管好您的 Access Token，确保它不会被泄露。

如何使用 Access Token

成功获取Access Token后，您就已经准备好开始使用画布 API 进行各类业务请求了。在向英飞画布服务发送 REST 请求时，您需要将获取到的 Access Token 添加至请求头部，示例如下：

curl https://developer.infi.cn/infi/api/v1/sampleAPI \
     -H "token: YOUR_ACCESS_TOKEN"
     ...

注意：

请确保将 YOUR_ACCESS_TOKEN 替换为您实际获得的 Token

请将 sampleAPI 替换为实际存在的业务接口

接下来我们将展示如何利用您的 Access Token 来执行第一个 API 请求，并介绍一些基本的 API 使用方法。

第一个 API 请求

拥有Access Token之后，您就可以开始发起向画布API的请求了。本节将指导您完成第一个API请求，我们将展示如何使用 Access Token 在请求中进行授权，并接收响应。

发起请求

作为演示，我们将发送一个 POST 请求来获取画布内的统计数据。您需要将之前获得的 Access Token 加入到 HTTP 请求的头部，以便系统验证您的身份。在您于开发者控制台中完成应用的注册后，为方便您体验画布，我们会自动为您创建一块 ID 为 HelloWorld 的空白画布，此处我们也会基于该画布来请求数据。以下是使用 curl 命令行工具发起请求的示例：

curl https://developer.infi.cn/infi/api/v1/statistics/boardData \
     --header "token: YOUR_ACCESS_TOKEN"
     --data '{"list": ["HelloWorld"]}'

注意：请确保将 YOUR_ACCESS_TOKEN 替换为您实际获得的 Token

接收响应

如果请求成功，画布 API 会返回一个 200 OK 的 HTTP 状态码，以及一个 JSON 格式的响应体，包含了 ID 为 HelloWorld 的画布统计数据，示例如下：

{
  "list": [
    {
      "recordId": "HelloWorld",
      "data": {
        "totalAccessView": 10,
        "totalUserView": 5,
        "totalMeeting": 0,
        "totalMeetingDuration": 0,
        "totalElement": 5,
        "totalNote": 0,
        "totalComment": 0,
        "totalText": 1,
        "totalFile": 2,
        "totalShape": 1,
        "totalPic": 1,
        "totalWeb": 0
      }
    }
  ]
}

该响应展示了画布的统计数据，包括画布访问用户数、访问次数、画布内元素数量等信息。

错误处理

如果请求未能成功，API将返回相应的HTTP错误状态码及描述。比如，如果提供的 Access Token 无效，您可能会遇到 401 Unauthorized 状态码。针对这种情况，您应该检查 Token 是否正确或是否已过期，必要时重新获取新 Token。详细接口错误信息请参考请求错误说明文档。

下一步

您已经完成了第一个 API 请求并成功获取了画布统计信息。我们鼓励您继续浏览文档以了解画布 API 的其他功能，比如创建新画布、编辑元素、管理会议和数据统计等。如遇到问题，欢迎查阅错误码章节获取帮助，或直接联系我们的技术支持团队。

Access Token​

获取 Access Token​

如何使用 Access Token​

第一个 API 请求​

发起请求​

接收响应​

错误处理​

下一步​