注入内容 REST API
要在服务器端注入内容到文档中，请使用本文档中描述的 PATCH 端点。此功能支持版本历史记录，跟踪更改以及通过此端点添加的内容。
更新文档的端点还允许 JSON 更新以修改您在协作服务器上的文档，包括本地部署和云端：
- 在任何文档服务器端添加
json、binary或base64内容。 - 使用 UniqueID 扩展 向特定节点注入内容。
- 用户仍然可以实时协作，因为内容在注入过程中。
- 跟踪用户和注入内容的更改，完全兼容 快照。
用例
内容注入 REST API 可以实现一些方便但复杂的用例：
- 文档内容的实时翻译。
- 在服务器端以编程方式标记或操作文档内容。
- 集成服务器端组件，例如执行 SQL 查询并显示结果。
- 版本历史集成和无冲突的并发编辑合并。
更新文档
要在协作服务器上更新现有文档，可以使用 PATCH 方法与以下 API 端点：
PATCH /api/documents/:identifier?format=:format此端点接受 Yjs 更新消息并将其应用于指定文档。format 查询参数指定更新的格式，可以是以下之一：
json：使用 JSON 格式更新文档（有一些注意事项，见下文）。binary：直接使用 Yjs 的Y.encodeStateAsUpdate方法。base64：将二进制状态编码为 Base64 字符串。
成功更新后，服务器将返回 HTTP 状态 204。如果文档不存在，将返回 404，如果负载无效或无法应用更新，将返回 422。
示例： 更新文档的 curl 命令
curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \\
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \\
--data '@yjsUpdate.binary.txt'通过 JSON 更新
通过 JSON 更新时，服务器计算当前文档状态与提供的 JSON 之间的差异，然后内部计算所需的 Yjs 更新以达到目标状态。
为了确保精确更新，特别是对于节点特定的更改，建议使用 nodeAttributeName 和 nodeAttributeValue 参数。这些可以通过 Tiptap 的 UniqueID 扩展 或自定义实现生成。
注意，这仅适用于顶层节点。
nodeAttributeName：在 UniqueID 扩展 中配置为attributeName。nodeAttributeValue：为正在更新的节点生成的唯一值。您可以通过?nodeAttributeValue=a&=nodeAttributeValue=b传递多个值。
您可以使用 ?mode=append 将节点附加到文档的 JSON 表示，而不更改现有节点。
省略这些参数可能会导致覆盖在获取文档和发出更新调用之间所做的任何更新。get document 调用返回一个头 x-${fragmentName}-checksum，可以通过将其传递给更新调用作为 ?checksum=${checksum} 来检测冲突。如果自上次获取以来文档已被更新，更新将以 409 Checksum mismatch. 状态失败。
示例： 使用 JSON 更新文档
// 定义文档名称、密钥和应用程序 ID
const docName = '' // 如有必要，请进行 URI 编码
const secret = ''
const appId = '';
// 构建基本 URL
const url = `https://${appId}.collab.tiptap.cloud`
// 获取当前文档的 JSON 表示
const docJson = await axios.get(`${url}/api/documents/${docName}?format=json`, {
headers: {
Authorization: secret
},
})
// 提取文档的 JSON 内容
const tiptapJson = docJson.data
const nodes = tiptapJson.content
// 使用唯一标识符查找并记录特定节点
const query = nodes.find(n => n.attrs?.identifier === 'fe5c0789-85d9-4877-a2c3-bccf5d874866').content[0].text
const resultTable = nodes.find(n => n.attrs?.identifier === '246368b6-0746-4ca1-a16f-8d964aff4041')
console.log(`Query: ${query}`)
console.log(JSON.stringify(resultTable.content))
// 向结果表节点附加新内容
resultTable.content.push({
// 新表行内容在此
{
"type": "tableRow",
"content": [
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "left"
},
"content": [
{
"type": "text",
"text": "Jan"
}
]
}
]
},
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "left"
},
"content": [
{
"type": "text",
"text": "Thurau"
}
]
}
]
},
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"type": "paragraph",
"attrs": {
"textAlign": "left"
},
"content": [
{
"type": "text",
"text": "jan@janthurau.de"
}
]
}
]
}
]
}
})
// 将更新后的 JSON 发送回服务器以应用更改
await axios.patch(`${url}/api/documents/${docName}?format=json`, tiptapJson, {
headers: {
Authorization: secret
}
})仅更新节点属性
如果您只想更新节点的属性，可以使用 ?mode=attrs 查询参数。这将仅更新节点的属性，而不更新其内容。
在此模式下，nodeAttributeName 和 nodeAttributeValue 参数适用于任何（不仅仅是顶层）节点。
请注意，我们将删除该节点上的所有属性，然后仅设置请求负载中指定的属性。不指定节点过滤器（nodeAttributeName, nodeAttributeValue）会导致所有节点被更新。
curl --location --request PATCH '/api/documents/:identifier?format=json&nodeAttributeName=id&nodeAttributeValue=12&mode=attrs' \
--data '{
"indent": 12,
"textAlign": "right"
}'
创建文档
要在 Tiptap Collab 服务器上创建新文档，请使用 POST 方法与以下端点：
POST /api/documents/:identifier?format=:format服务器将返回成功创建的 HTTP 状态 204，如果文档已存在则返回 409（您必须先删除它以覆盖），如果操作失败则返回 422。
format 参数接受与更新端点相同的值（binary、base64 或 json）。