一、获取并配置有效的 x-auth-token
想通过程序调用语雀的接口？第一步，也是绕不开的一步，就是搞定身份认证。语雀的所有受保护接口，都要求在请求头里带上一个叫 x-auth-token 的凭证。没有它，或者它失效了，服务器只会冷冰冰地回你一个 401 Unauthorized 错误。
那么，这个关键的令牌从哪里来呢？操作路径其实很清晰：
1. 登录语雀官网，点击页面右上角的个人头像，进入「个人设置」。
2. 在左侧的菜单栏里，找到并点击「API 令牌」选项。
3. 接着，点击「创建新令牌」按钮。这时，你需要为这个令牌起个名字（比如“数据备份脚本”），并根据你的需求勾选权限范围。如果只是读取文档，建议至少勾选 read:repo 和 read:doc。
4. 点击确认后，页面上会显示一串 Token 字符串。这里有个至关重要的提醒：请务必立即复制并妥善保存这串字符。页面一旦刷新，你就再也看不到它了。
二、构造符合规范的 HTTP 请求头与参数
拿到了通行证，接下来就得学会“敲门”的规矩。语雀的 API 对请求的格式有明确要求，参数不对路，很可能吃个 400 Bad Request 的闭门羹。
首先，构造请求头是必须的。你需要确保每个请求都包含以下两个字段：
1. "User-Agent": 这里可以填写你的应用名称和版本，例如 "my-backup-tool/1.0"。
2. "x-auth-token": 这里就填入你上一步复制保存的那串令牌。
其次，参数传递也得讲究方法：
对于 GET 请求（比如后面要用的搜索接口），你需要把查询参数进行 URL 编码，然后老老实实地拼接在请求地址的末尾。
而对于 POST 请求，请求体必须是标准的 application/json 格式，并且 JSON 里的字段名要和官方文档的定义一字不差。举个例子，在路径参数里，你得用 slug，而不是想当然地用 id。
三、调用文档搜索接口定位目标文档
如果你的知识库里文档成百上千，想精准找到某一篇，或者想批量处理某些文档，搜索接口就是你的好帮手。它能帮你在指定的知识库里按关键词筛选，返回的列表里包含了每篇文档的 slug、标题、更新时间等关键信息，是后续操作的基础。
具体该怎么调用呢？
1. 请求的 URL 是固定的：https://www.yuque.com/api/v2/search。
2. 设置查询参数时，有几个关键点：scope 参数必须填写完整的知识库路径（格式如 username/repo_name）；q 参数填你的搜索关键词（记得做 UTF-8 编码）；type 参数固定填写为 doc。
3. 发起 GET 请求后，先别急着处理数据。检查一下响应状态码是不是 200，确认成功后再去解析 response.json().data.items 这个数组，里面就是你要的文档条目。
4. 从每个条目中，提取出 slug 这个字段的值。这个小小的字符串，将是下一步获取文档完整内容的钥匙。
四、获取单篇文档的完整内容
拿到了文档的 slug，就好比拿到了具体房间的房号，现在可以进去一探究竟了。通过这个接口，你可以获取到文档的完整结构化内容，包括标题、原始的 Markdown 正文、渲染后的 HTML、创建者、更新时间等等。无论是想存档备份，还是做格式转换，甚至直接在前端渲染，都靠它。
调用步骤很直接：
1. 构造请求 URL：https://www.yuque.com/api/v2/repos/{namespace}/{slug}。这里需要替换两个变量：{namespace} 是知识库路径（不含域名部分），{slug} 就是上一步拿到的那把“钥匙”。
2. 确保你的请求头里已经正确配置好了 x-auth-token 和 User-Agent。
3. 发送 GET 请求。当响应状态码 status_code 等于 200 时，就可以从 response.json().data.body 字段中读取到原始的 Markdown 文本了。
4. 这里有个实用的细节：接口返回的 body_html 字段虽然方便，但里面包含了语雀私有的样式类名（比如 yuque-content）。如果你需要干净、通用的 HTML，建议还是使用 body 字段的 Markdown 原文，然后用一个标准的 Markdown 渲染器来处理。
五、使用官方 SDK 简化调用流程
如果你是在 Node.js 环境下开发，觉得手动构造 HTTP 请求、处理头信息、管理分页太繁琐，那么语雀官方提供的 SDK (@yuque/sdk) 能让你事半功倍。它帮你封装了底层细节，让调用过程更简洁。
怎么用呢？分四步走：
1. 首先，在项目根目录下执行 npm install @yuque/sdk 安装这个依赖包。
2. 接着，在代码里初始化客户端：const client = new SDK({ token: 'your_token_here' })，记得把令牌替换成你自己的。
3. 然后，就可以愉快地调用封装好的方法了。比如，用 client.repos.list() 获取知识库列表，用 client.docs.get({ repo_id, slug }) 获取某篇文档的详情。
4. 这些方法返回的都是 Promise 对象，所以你需要用 async/await 或者 .then() 来处理异步响应。另一个好处是，错误处理也统一了：所有错误都会抛出 SDKError 实例，你可以通过检查 error.code 来区分是网络问题、权限不足还是参数有误。
