CKEditor 生态系统文档
Search
首页/云服务/入门

guide文档存储

# 概述

文档存储功能允许您将协作数据永久保存到 CKEditor 云服务。启用后，文档将不再 仅在文档会话生命周期内临时存储。相反，协作会话数据将永久保存到 CKEditor 云服务服务器。

保存在文档存储中的数据包含以下内容

  • 内容 - 它是编辑文档的完整内容。它等同于调用 editor.getData() 的结果。
  • 操作 - 它是编辑会话期间进行的每个文档更新（文档历史记录），存储为 对象模型。这些操作以压缩状态存储。
  • 版本 - 文档的当前版本。版本根据执行的不同操作的数量确定。

当用户连接到之前存在的文档（其协作会话已过期）时，将使用文档存储中存储的内容初始化新的协作会话。

您的服务器完全无需负责保存文档。您无需为获取协作数据、将其保存到您的数据库以及使用先前保存的数据初始化文档编写任何额外的逻辑。这些操作将由 CKEditor 云服务自动处理。

# 先决条件

要使用文档存储功能，需要将具有其配置的编辑器上传到 CKEditor 云服务服务器。云服务使用您的编辑器在保存之前生成正确的结果数据，并使用先前存储的数据初始化协作会话。由于这种方法，您的自定义插件（可能会生成一些自定义数据）也将正常工作。

在开始使用此功能之前，需要执行两个步骤

  1. 将您的编辑器包（包含编辑器配置）上传到 CKEditor 云服务服务器。有关更多信息，请参阅 编辑器包 指南。
  2. 在编辑器配置中设置所需的 bundleVersion 属性。有关更多详细信息，请参阅编辑器包文档的 编辑器配置 部分。

# 启用文档存储功能

按照以下步骤设置文档存储功能。

  1. 登录到 CKEditor 生态系统仪表板 并导航到“您的产品 > 云服务”。

如果您有兴趣使用 协作服务器本地部署 的文档存储功能，您需要登录到 云服务管理面板，您可以跳过下一步。

  1. 从仪表板中可用的订阅列表中，选择您要管理的订阅，然后单击“管理”链接。

Your products view in the CKEditor Ecosystem customer dashboard.

  1. 选择您要启用文档存储功能的环境。如果需要，可以使用“创建新环境”按钮创建一个环境。

Select the environment that you want to manage.

  1. 导航到“功能配置”选项卡，并在“存储 > 文档存储”部分打开此功能。

Navigate to the Feature configuration tab and switch on the Document storage feature

请记住，文档存储功能仅在启用它的环境中起作用。如果您使用多个环境，则需要分别为每个环境启用此功能。

关闭此功能将删除给定环境的所有存储的文档。

# 用法

# 启动协作会话

启用文档存储后，会话将使用存储在 CKEditor 协作服务器数据库中的数据自动创建。无需执行任何其他操作，使用 channelId 值初始化编辑器将加载存储的内容。

在通过文档存储初始化编辑会话期间，只要上传的 编辑器包版本 不变，就会使用文档存储中保存的压缩操作创建结果文档内容。

初始化协作会话的过程如下

  1. 用户想要打开具有给定 channelId 的文档，编辑器开始初始化。
  2. CKEditor 协作服务器检查内容是否已存储在文档存储中。
  3. 编辑器使用存储的文档数据初始化。

The workflow of initializing collaboration sessions with document storage.

如果在文档存储中找不到给定 channelId 的数据，则将改为使用编辑器配置中的 initialData 属性。您可以使用此属性从某些模板初始化新文档，或使用空字符串作为 initialData 值初始化空文档。或者，您可以使用 协作会话导入 功能，并将初始内容作为请求正文中的 data 属性传递。

# 保存文档

上传编辑器包并启用此功能后，加密的协作数据将自动保存到 CKEditor 云服务数据库。有几种情况会触发文档保存操作

  • 任何用户在文档中进行的操作（每 5 分钟一次），
  • 用户对文档进行 1000 次操作，
  • 最后一个用户断开协作会话连接，
  • 创建新文档（由用户创建或通过 REST API 导入文档），
  • 使用 REST API 刷新协作会话。

可以使用 REST API 手动触发文档保存操作。

只要没有使用相同 ID 的活动协作会话，您也可以通过 REST API 将文档同步导入存储。

CKEditor 云服务不会保留多个版本的文档。只有最新的文档版本可用。

# 文档存储 Webhook

您可以通过 Webhook 事件的形式接收有关文档存储中文档处理的信息。有关更多详细信息，请参阅 文档存储事件 部分。

在设置文档存储时，文档存储 Webhook 非常有用。您可以快速验证文档是否已正确保存，以及在此过程中是否存在任何问题。

某些用例可能需要在您的应用程序中拥有内容的副本。要同步 CKEditor 协作服务器和您的应用程序之间的内容，您可以使用 storage.document.saved Webhook 来接收新版本文档可用的信号。这可以触发 REST API 请求以 获取 CKEditor 协作服务器中的内容，然后将其存储在您的数据库中。

保持文档同步的推荐流程如下

  1. 用户操作或 REST API 请求触发文档存储保存。
  2. 文档内容保存在 CKEditor 协作服务器数据库中。
  3. CKEditor 协作服务器发出 storage.document.saved Webhook，其中包含 channelId 属性。
  4. 收到 Webhook 后，发送 GET /storage/{document_id} 请求。
  5. 将文档内容存储在您的数据库中。

The workflow of saving the content of the documents when using document storage.

# 文档管理

您可以使用 REST API 中提供的方法管理存储的文档。可用的文档存储方法有

  • POST /storage – 将文档内容导入存储。它可以是 HTML 内容，也可以是 多根编辑器 创建的文档的字符串化 JSON 结构。在后一种情况下，键是根名称，值是特定根的 HTML 内容。
  • GET /storage/{document_id} – 获取存储中保存的单个文档的内容。它可以是 HTML 内容，也可以是 多根编辑器 创建的文档的字符串化 JSON 结构。在后一种情况下，键是根名称，值是特定根的 HTML 内容。
  • GET /storage – 获取存储中保存的文档 ID 列表。
  • DELETE /storage/{document_id} – 从存储中删除单个文档。

# 示例

查看 在 Node.js 和 Express.js 中使用文档存储功能的应用程序示例。

此外，您还可以查看 CKEditor 云服务示例库，其中包含更多示例。

# 调试

如有必要，可以将所有协作数据存储以用于调试目的。这将使我们的客户支持团队能够检查与文档存储功能相关的错误。请仅在我们的客户支持团队要求您这样做时启用此选项。