一、获取并配置有效的 x-auth-token

想通过程序调用语雀的接口？第一步，也是绕不开的一步，就是搞定身份认证。

语雀的所有受保护接口，都要求在请求头里带上一个叫 x-auth-token 的凭证。没有它，或者它失效了，服务器只会回你一个 401 Unauthorized 错误。

获取令牌的步骤

这个关键的令牌从哪里来呢？操作路径很清晰：

• 登录语雀官网，点击页面右上角的个人头像，进入「个人设置」。
• 在左侧菜单栏里，找到并点击「API 令牌」选项。
• 点击「创建新令牌」按钮。你需要为令牌起名，并根据需求勾选权限范围。如果只是读取文档，建议至少勾选 read:repo 和 read:doc。
• 点击确认后，页面上会显示一串 Token 字符串。

请务必立即复制并妥善保存这串字符。页面一旦刷新，你就再也看不到它了。

二、构造符合规范的 HTTP 请求头与参数

拿到了通行证，接下来就得学会“敲门”的规矩。语雀的 API 对请求格式有明确要求，参数不对路，很可能收到 400 Bad Request 错误。

构造请求头

你需要确保每个请求都包含以下两个字段：

• "User-Agent"：填写你的应用名称和版本，例如 "my-backup-tool/1.0"。
• "x-auth-token"：填入你上一步复制保存的那串令牌。

参数传递方法

参数传递也得讲究方法：

• 对于 GET 请求，你需要把查询参数进行 URL 编码，然后拼接在请求地址的末尾。
• 对于 POST 请求，请求体必须是标准的 application/json 格式，并且 JSON 里的字段名要和官方文档的定义一字不差。

例如，在路径参数里，你得用 slug，而不是想当然地用 id。

三、调用文档搜索接口定位目标文档

如果你的知识库里文档成百上千，想精准找到某一篇，或者想批量处理某些文档，搜索接口就是你的好帮手。

它能帮你在指定的知识库里按关键词筛选，返回的列表里包含了每篇文档的 slug、标题、更新时间等关键信息。

调用方法

具体该怎么调用呢？

• 请求的 URL 是固定的：https://www.yuque.com/api/v2/search。
• 设置查询参数时，有几个关键点：
  • scope 参数必须填写完整的知识库路径（格式如 username/repo_name）。
  • q 参数填你的搜索关键词（记得做 UTF-8 编码）。
  • type 参数固定填写为 doc。
• 发起 GET 请求后，先检查响应状态码是不是 200。确认成功后再去解析 response.json().data.items 这个数组。
• 从每个条目中，提取出 slug 这个字段的值。这个字符串是下一步获取文档完整内容的钥匙。

四、获取单篇文档的完整内容

拿到了文档的 slug，就好比拿到了具体房间的房号，现在可以进去一探究竟了。

通过这个接口，你可以获取到文档的完整结构化内容，包括标题、原始的 Markdown 正文、渲染后的 HTML、创建者、更新时间等。

调用步骤

调用步骤很直接：

• 构造请求 URL：https://www.yuque.com/api/v2/repos/{namespace}/{slug}。这里需要替换两个变量：
  • {namespace} 是知识库路径（不含域名部分）。
  • {slug} 就是上一步拿到的那把“钥匙”。
• 确保你的请求头里已经正确配置好了 x-auth-token 和 User-Agent。
• 发送 GET 请求。当响应状态码 status_code 等于 200 时，就可以从 response.json().data.body 字段中读取到原始的 Markdown 文本了。

这里有个实用的细节：

接口返回的 body_html 字段虽然方便，但里面包含了语雀私有的样式类名（比如 yuque-content）。如果你需要干净、通用的 HTML，建议还是使用 body 字段的 Markdown 原文，然后用一个标准的 Markdown 渲染器来处理。

五、使用官方 SDK 简化调用流程

如果你是在 Node.js 环境下开发，觉得手动构造 HTTP 请求、处理头信息、管理分页太繁琐，那么语雀官方提供的 SDK (@yuque/sdk) 能让你事半功倍。

它帮你封装了底层细节，让调用过程更简洁。

使用步骤

怎么用呢？分四步走：

• 首先，在项目根目录下执行 npm install @yuque/sdk 安装这个依赖包。
• 接着，在代码里初始化客户端：const client = new SDK({ token: 'your_token_here' })，记得把令牌替换成你自己的。
• 然后，就可以愉快地调用封装好的方法了。比如：
  • 用 client.repos.list() 获取知识库列表。
  • 用 client.docs.get({ repo_id, slug }) 获取某篇文档的详情。
• 这些方法返回的都是 Promise 对象，所以你需要用 async/await 或者 .then() 来处理异步响应。

另一个好处是，错误处理也统一了：

所有错误都会抛出 SDKError 实例，你可以通过检查 error.code 来区分是网络问题、权限不足还是参数有误。

《夸克》非常好用的免费AI浏览器

下载APP查看