--- title: "文档管理 API" description: "使用协作管理 API 以编程方式管理您的 Tiptap 文档。在文档中了解更多信息。" canonical_url: "https://tiptap.zhcndoc.com/collaboration/documents/rest-api" --- # 文档管理 API 使用协作管理 API 以编程方式管理您的 Tiptap 文档。在文档中了解更多信息。 协作管理 API 提供了一套 RESTful 接口，用于管理文档。此 API 可用于文档的创建、列出、检索、更新、删除和复制。 您可以通过访问我们的 [Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-cc186a66-df41-4df8-9c6e-e91b20deffe5) 来体验 REST API。 ## 速率限制 为维护系统的完整性并防止配置错误的客户端，我们的基础设施——包括管理 API 和通过 `TiptapCollabProvider` 的 websocket 连接——受到速率限制。 ### 默认速率限制（每个源 IP）： - **请求数：** 100 - **时间窗口：** 5 秒 - **突发容量：** 最多 200 个请求 如果您在正常操作下遇到这些限制，请 [给我们发邮件](mailto:humans@tiptap.dev)。 ## 访问 API REST API 直接从您的文档服务器以自定义 URL 公开： ```bash https://YOUR_APP_ID.collab.tiptap.cloud/ ``` 将 `YOUR_APP_ID` 替换为您的文档服务器 ID，该 ID 在 [Cloud 控制台](https://cloud.tiptap.dev/v2/configuration/document-server) 中标示为"Document server ID"。 ### 身份验证 使用携带 `Documents:Api:All` 权限的签名 token 对您的 API 请求进行身份验证，并通过 `Authorization: Bearer ` 发送。有关如何签名 token，请参阅 [身份验证](https://tiptap.zhcndoc.com/authentication.md)。 > **Keep this token server-side:** > > `Documents:Api:All` 可访问每个 Document Server API 端点，包括受管理的设置。请将携带该权限的 token 视为管理员凭证。请在您的服务器上签名，保持其短期有效，并且绝不要暴露给客户端。 之前的 API secret 仍然有效，并在 [旧版身份验证](https://tiptap.zhcndoc.com/authentication/legacy.md) 中有文档说明。 ### 文档标识符 如果您的文档标识符包含斜杠 (`/`)，请将其编码为 `%2F`，例如，使用 `encodeURIComponent`。 ## API 端点概述 访问协作管理 API 以高效管理您的文档。有关 Tiptap 产品中所有端点的全面视图，请查看我们的 [Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-cc186a66-df41-4df8-9c6e-e91b20deffe5)，其中包括详细示例和配置。 | 操作 | 方法 | 端点 | 描述 | | ------ | ---------- | ------------------------------------------ | --------------------------- | | 创建文档 | POST | `/api/documents/:identifier` | 使用 `yjs` 或 `json` 更新消息创建文档。 | | 批量导入文档 | PUT | `/api/admin/batch-import` | 批量导入多个文档。 | | 获取文档 | GET | `/api/documents/:identifier` | 以 `json` 或 `yjs` 格式导出文档。 | | 列出文档 | GET | `/api/documents` | 检索带有分页选项的所有文档列表。 | | 复制文档 | POST + GET | `/api/documents/:identifier` (GET 然后 POST) | 通过检索文档然后使用新标识符创建文档来复制文档。 | | 加密文档 | POST | `/api/documents/:identifier/encrypt` | 使用 Base64 加密文档。 | | 回退到版本 | POST | `/api/documents/:identifier/versions` | 回退文档到指定版本。 | | 更新文档 | PATCH | `/api/documents/:identifier` | 将 Yjs 更新消息应用于现有文档。 | | 删除文档 | DELETE | `/api/documents/:identifier` | 从服务器中删除文档。 | | 搜索文档 | POST | `/api/search` | 对所有文档执行搜索。 | 同时查看 [指标和统计端点](https://tiptap.zhcndoc.com/collaboration/operations/metrics.md)! ## 创建文档 ```bash POST /api/documents/:identifier ``` 此调用允许您使用 [二进制 Yjs](https://tiptap.zhcndoc.com/collaboration/getting-started/overview.md#about-yjs) 或 JSON 格式（默认：`yjs`）创建文档。它可用于在用户连接到 Tiptap 协作服务器之前预置文档。 如果文档成功创建，该端点返回 HTTP 状态 `204`，如果文档已存在，则返回 `409`。要覆盖现有文档，您必须首先 [删除它](https://tiptap.zhcndoc.com/collaboration/documents/rest-api.md#delete-a-document)。 - **Yjs 格式**：要使用 Yjs 二进制更新消息创建文档，首先使用 `Y.encodeStateAsUpdate` 编码 Yjs 文档。 ```bash curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \ --header 'Authorization: Bearer YOUR_JWT' \ --data '@yjsUpdate.binary' ``` - **JSON 格式**：要使用 JSON 创建文档，传递查询参数 `format=json` 并在 Tiptap JSON 格式中包含文档的内容。 ```bash curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \ --header 'Authorization: Bearer YOUR_JWT' \ --header 'Content-Type: application/json' \ --data '{ "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "这是您的内容。" } ] } ] }' ``` ## 批量导入文档 ```bash PUT /api/admin/batch-import ``` 此调用允许您使用预定义的 JSON 结构批量导入多个文档。每个文档必须包含其元数据（如 created\_at、name 和 version）以及 Tiptap JSON 格式的内容。 如果文档成功导入，该端点返回 HTTP 状态 `204`，如果请求包含无效数据，则返回 `400`。 ```bash curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/batch-import' \ --header 'Content-Type: application/json' \ --data '[ [ { "created_at": "2024-05-01T10:00:00Z", "version": 0, "name": "文档-1", "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-1 的文本：v0"}]}]} }, { "created_at": "2024-05-01T11:00:00Z", "version": 1, "name": "文档-1", "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-1 的文本：v1"}]}]} } ], [ { "created_at": "2024-06-01T10:00:00Z", "version": 0, "name": "文档-2", "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-2 的文本：v0"}]}]} }, { "created_at": "2024-06-01T11:00:00Z", "version": 1, "name": "文档-2", "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-2 的文本：v1"}]}]} } ] ]' ``` ## 获取文档 ```bash GET /api/documents/:identifier?format=:format&fragment=:fragment&version=:version ``` 此调用允许您以 JSON 或 Yjs 格式导出指定文档及其所有片段。如果文档当前在您的服务器上打开，我们将返回内存中的版本；否则，我们将从数据库读取。 - `format` 支持 `yjs`、`base64`、`text` 或 `json`（默认：`json`）。如果您选择 `yjs` 格式，您将获得使用 `Y.encodeStateAsUpdate` 创建的二进制 Yjs 更新消息。 - `fragment` 可以是一个数组（例如，`fragment=a&fragment=b`）或您想要导出的单个片段。默认情况下，我们只导出 `default` 片段。此参数仅在使用 `json` 或 `text` 格式时适用；在使用 `yjs` 时，您将始终获得整个 Yjs 文档。 - `version`（`string`，可选）：要检索的 Y.js 文档版本。默认为最新版本。 ```bash curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \ --header 'Authorization: Bearer YOUR_JWT' ``` 当使用 `axios` 时，您需要在请求选项中指定 `responseType: arraybuffer`。 ```typescript import * as Y from 'yjs' const ydoc = new Y.Doc() const axiosResult = await axios.get( 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs', { headers: { Authorization: 'Bearer YOUR_JWT', }, responseType: 'arraybuffer', }, ) Y.applyUpdate(ydoc, axiosResult.data) ``` 当使用 `node-fetch` 时，您需要使用 `.arrayBuffer()` 并从中创建一个 Buffer： ```typescript import * as Y from 'yjs' const ydoc = new Y.Doc() const fetchResult = await fetch( 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs', { headers: { Authorization: 'Bearer YOUR_JWT', }, }, ) Y.applyUpdate(ydoc, Buffer.from(await fetchResult.arrayBuffer())) ``` ## 列出文档 ```bash GET /api/documents?take=100&skip=0 ``` 此调用返回存储中所有文档的分页列表。默认情况下，我们返回前 100 个文档。传递 `take` 和 `skip` 参数以调整分页。 ```bash curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents' \ --header 'Authorization: Bearer YOUR_JWT' ``` ## 复制文档 此调用允许您复制或重复文档。首先，使用 `GET` 端点检索文档，然后使用 `POST` 调用创建一个新文档。以下是 TypeScript 的示例： ```typescript const docUpdateAsBinaryResponse = await axios.get( 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs', { headers: { Authorization: 'Bearer YOUR_JWT', }, responseType: 'arraybuffer', }, ) await axios.post( 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME-duplicated', docUpdateAsBinaryResponse.data, { headers: { Authorization: 'Bearer YOUR_JWT', }, }, ) ``` 请注意，新文档将不会拥有源文档的版本记录。如果您想保留版本，可以使用导入/导出端点（参见 Postman 集合）。 ## 加密文档 ```bash POST /api/documents/:identifier/encrypt ``` 此调用允许您使用 Base64 加密指定标识符的文档。 如果文档成功加密，该端点返回 HTTP 状态 `204`，如果文档不存在，则返回 `404`。 ```bash curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/encrypt' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_JWT' \ --data '{ "type": "doc", "content": [ { "type": "paragraph", "attrs": { "indent": 0, "textAlign": "left" }, "content": [ { "text": "整个文档将被替换为此（除非您将模式参数更改为 '\''append'\''）", "type": "text" } ] } ] }' ``` ## 版本管理 版本记录了文档在某一时间点的状态。每个版本都有一个 `version` 编号、`date`，以及可选的 `name` 和 `meta`（任意元数据对象）。 每个版本的 `meta` 对象会自动包含一个 `__tiptap` 键，其中包含服务器生成的有关谁贡献了更改以及版本是如何创建的元数据。详情请参见 [自动版本元数据](https://tiptap.zhcndoc.com/collaboration/documents/snapshot.md#automatic-version-metadata)。 如需查看所有版本端点的完整交互式参考，请参见 [Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-a6e8aa7e-c077-46ee-a2a3-241f8efd5d25?action=share\&creator=33042171\&active-environment=33042171-378cfb31-9c16-40f0-95b8-b9f0d3c7d2ab)。 ### 回退到版本 ```bash POST /api/documents/:identifier/versions/:versionId/revertTo ``` 此调用允许您将文档回退到特定的先前版本，通过应用与文档先前状态对应的更新。 如果文档成功回退，该端点返回 HTTP 状态 `204`，如果文档或版本未找到，则返回 `404`。 ```bash curl --location --request POST 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/versions/VERSION_ID/revertTo' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_JWT' ``` ### 更新版本 ```bash PATCH /api/documents/:identifier/versions/:versionId ``` 此调用允许您更新版本的名称或元数据。您可以用它来重命名版本或在创建后附加更多上下文。 有关请求体参数和示例，请参阅 [Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-a6e8aa7e-c077-46ee-a2a3-241f8efd5d25?action=share\&creator=33042171\&active-environment=33042171-378cfb31-9c16-40f0-95b8-b9f0d3c7d2ab)。 ## 更新文档 ```bash PATCH /api/documents/:identifier ``` 此调用接受一个 Yjs 更新消息并将其应用于服务器上现有文档。 如果文档成功更新，该端点返回 HTTP 状态 `204`，如果文档不存在，则返回 `404`，如果有效负载无效或无法应用更新，则返回 `422`。 ```bash curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \ --header 'Authorization: Bearer YOUR_JWT' \ --data '@yjsUpdate.binary' ``` API 端点还支持 JSON 文档更新、用于跟踪更改的文档历史记录以及特定节点的更新。 有关使用 JSON 而不是 Yjs 操作文档的更详细信息，请参阅我们的 [内容注入](https://tiptap.zhcndoc.com/collaboration/documents/content-injection.md) 页面。 ## 删除文档 ```bash DELETE /api/documents/:identifier ``` 此调用在关闭与文档的任何连接后从服务器中删除文档。 如果文档成功删除，它返回 HTTP 状态 `204`，如果文档未找到，则返回 `404`。 ```bash curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \ --header 'Authorization: Bearer YOUR_JWT' ``` > **删除后文档仍然存在:** > > 如果端点返回 `204` 但文档仍然存在，请确保没有用户正在从提供者重新创建文档。在删除文档之前，我们会关闭所有连接，但您的错误处理可能会重新创建提供者，从而再次创建文档。 ## 搜索文档 ```bash POST /api/search ``` 当 [Tiptap 语义搜索](https://tiptap.zhcndoc.com/collaboration/documents/semantic-search.md) 启用时，您可以在所有文档中执行上下文相关的搜索。 > **保持您的 API 密钥秘密:** > > 请在后端处理搜索请求以保持您的 API 密钥安全。考虑根据需要在您的应用程序中强制执行速率限制。 ### 查询参数 您可以使用以下查询参数来调整搜索结果： | 查询参数 | 类型 | 默认 | 描述 | | ----------- | ----- | ----- | ----------------------------- | | `threshold` | float | `0.5` | 描述文档的相似性因子。值可以在 `0` 和 `1` 之间。 | | `limit` | int | `20` | 限制结果数。值可以在 `1` 和 `100` 之间。 | ### 请求体参数 | 请求体参数 | 类型 | 默认 | 描述 | | --------- | ------ | -- | ------ | | `content` | string | - | 您的搜索词。 | ```bash curl -X POST https://YOUR_APP_ID.collab.tiptap.cloud/api/search \ -H "Authorization: YOUR_SECRET_FROM_SETTINGS_AREA" \ -H "Content-Type: application/json" \ -d '{"content": "your search term"}' ```