修订版本

04/09/2025, by Ivan

Download JSON Drop API

JSON:API 模块将实体修订版本公开为资源版本，其方式受 RFC5829：用于 Web 资源之间简单版本导航的链接关系类型启发。

当前限制：

资源版本（实体修订版本）只能读取。而且只有 Node 和 Media 实体类型（node--* 和 media--* 资源类型）才能通过 JSON:API 访问资源版本（由于 Drupal 核心中缺少正式的实体修订访问控制 API，一旦该功能可用，我们将使所有可修订的实体类型都可以通过 JSON:API 访问，参见 #3031271: 支持任意实体类型的版本协商（当前仅支持 Node 和 Media））。
然而，当对配置为自动创建新版本（修订版）的资源类型（实体类型 + bundle）执行 PATCH 时，资源版本会自动创建。我们正在开发功能，使得对可版本化资源的 PATCH 请求可以指定是否应创建新修订版，参见 #2993557: 允许在通过 JSON:API PATCH 修订实体时选择性地创建新修订，以支持自动保存功能。

修订支持并不是 JSON:API 规范的官方部分。然而，正在开发一些 “profiles”（也不是规范的官方部分，但已被纳入 JSON:API v1.1），以标准化 JSON:API 模块开发的任何自定义行为（所有这些仍符合规范）。

这样做的目的是使 JSON:API 模块最大程度兼容其他系统，并尽量减少开发者在使用 JSON:API 实现时需要了解的 “Drupalisms”。

在 JSON:API 模块中，“版本” 是指以前或当前为默认修订的任何修订。并非所有修订都被视为 “版本”。未标记为 “默认” 修订的修订被视为 “工作副本”，因为它们通常不会公开，并且是应用大多数新工作的修订。

当启用内容审核（Content Moderation）模块时，最新的默认修订可能不是最新的修订。

请求资源版本是通过 URL 查询参数完成的。其形式如下：

            version-identifier
                  __|__
                 /     \
?resourceVersion=foo:bar
                 \_/ \_/
                  |   |
  version-negotiator  |
              version-argument

版本标识符是一个包含足够信息以加载特定修订的字符串。版本协商器部分命名用于加载修订的协商机制。目前，它可以是 id 或 rel。id 协商器接受修订 ID 作为版本参数。rel 协商器接受的版本参数可以是字符串 latest-version 或字符串 working-copy。

未来，可能会开发其他协商器。例如，基于时间戳或工作区的协商器。

为了说明如何请求特定的实体修订，假设一个节点有一个 “已发布” 修订和一个后续的 “草稿” 修订。

使用 JSON:API，可以通过请求 /jsonapi/node/page/{{uuid}}?resourceVersion=rel:latest-version 来请求 “已发布” 节点。

要预览仍在进行中的实体（即 “草稿” 修订），可以请求 /jsonapi/node/page/{{uuid}}?resourceVersion=rel:working-copy。

要请求特定的修订 ID，可以请求 /jsonapi/node/page/{{uuid}}?resourceVersion=id:{{revision_id}}。

目前还不能请求修订集合。此功能仍在开发中，参见 #3009588: 提供一个集合资源，以便获取版本历史（`version-history`、`predecessor-version` 和 `successor-version` 链接关系）。

文章来源：Drupal 文档。

Extra Block Types (EBT) - New Layout Builder experience❗

❗Extra Paragraph Types (EPT) - New Paragraphs experience

JSON Drop API Documentation