管理版本堆栈

概述

版本堆栈是 Frame.io 中的一种组织原则，它可以让资产垂直“堆叠”，而无需放进文件夹里。堆叠后的版本使得在 Frame.io UI 中更容易地在资产之间进行导航，并支持并排审阅。

我们目前不支持直接上传到堆栈中，因此管理基本版本堆栈工作流的 API 序列将与 Frame.io UI 的序列相同：

1. 上传资产（可选：标记为私有）。
2. 将资产分配到堆栈中。

现有版本堆栈可以重新排序，单个版本可以从堆栈中移除。最后，版本堆栈可以删除，而不会删除其任何组成资产。

核心概念

版本堆栈与文件夹一样，都是资产的特殊类型。您可以使用相同的端点来获取它们，并根据 API 响应中 type 键的值进行相应的解析和路由。这在实际操作中通常很简单，但在大规模管理堆栈时可能会遇到一些小问题。使用版本堆栈的关键在于区分以下四种最常见的场景：

1. 一个资产可以添加到另一个资产上，这将创建一个带有新 id 的堆栈。
2. 一个资产可以添加到现有堆栈中。
3. 可以重新排序堆栈。
4. 可以移除单个版本。

前两种场景使用相同的端点调用，因此唯一真正的细微差别在于要知道您是在用两个资产创建一个新的堆栈，还是将您的资产添加到现有堆栈中。除此之外，其限制条件是可预见的：

1. 堆栈中的 asset_type 必须匹配（例如，您不能将 图像 堆叠到 视频流 上）。
2. 操作用户必须对源资产和目标资产或堆栈都有权限。
3. 资产按顺序堆叠。
4. 您不能将一个堆栈堆叠在另一个堆栈上。
5. 文件夹则完全不行。

后两种场景也非常简单，但需要对堆栈本身有更多的了解。例如，要对堆栈中的资产进行重新排序，您需要知道目标资产将放置位置两侧的资产的 id；这通常意味着您已经获取了整个堆栈的信息。

必需的权限范围

在开始本指南之前，您需要确保拥有一个包含以下权限范围的令牌：

将资产添加到版本堆栈

步骤 1：定位您的目标

第一步是要确定您正处于两种关键场景中的哪一种——是将一个资产添加到另一个资产以创建一个堆栈，还是将一个资产添加到一个堆栈中以扩展该堆栈。

如果您知道自己正在使用一个尚未版本化的资产，或者您已拥有一个版本堆栈 id，则可以进入步骤 2。

如果不是这样，判断目标资产是否已经属于某个堆栈的最简单方法是：

1. 通过调用 /v2/assets/:id​ 来 GET 您的目标资产

2. 检查返回结果中的 type 值。

• 如果是 version_stack，那么您刚才检查的 uuid 就是您的目标 uuid。进入步骤 2。

3. 如果 type 值是 file，则获取 parent_id
4. 通过同一端点 GET 主项，并检查其 type 值。

如果主项的 type 是 version_stack，则使用其 id 作为您的目标。如果 type 是其他任何值，那么您正在处理的是一个普通资产，可以直接使用原始 id 作为目标。

步骤 2：准备您的负载

现在您已经有了目标 uuid，您需要知道要添加到堆栈中的资产的 uuid。

1. 如果您要上传新的资产，只需使用创建资产时成功响应中返回的 id 即可。
2. 如果您要堆叠现有资产，您应该已通过上述流程获得了它的 id。

添加版本堆栈时所需的唯一请求体参数是 next_asset_id：

1
{
2
    "next_asset_id": "<source-asset-id>"
3
}

步骤 3：将源资产添加到目标位置

现在您已拥有两个资产 id 参数，可以发起 POST 请求 /assets/:id/version，其中 :id 是您的目标资产或版本堆栈，而您的源（新）资产则在请求体中。

重新排序版本堆栈

版本堆栈依赖于一个简单的顺序概念：每个资产都拥有 next_asset_id 和 prev_asset_id 相邻项，其中顺序不是指版本编号，而是指每个资产的 index 属性。index 与版本号的顺序相反，因此相应地：

• 堆栈中的第一个（版本号最低的）版本拥有 prev 资产，但没有 next 资产
• 堆栈中的最新（版本号最高的）版本拥有 next 资产，但没有 prev 资产
• 所有“中间”的版本同时拥有 prev 和 next 资产，分别是版本 ID 较高和较低的资产。

这为我们提供了三种不同的场景，它们都依赖于同一个端点调用：

调用：

PUT https://api.frame.io/v2/asset/:id/tween

请求体：

1
{
2
  "prev_asset_id": "<asset_id>",
3
  "next_asset_id": "<asset_id>"
4
}

在所有情况下，URL 路径中的 id 都将是您要移动的资产。

移除资产与删除版本堆栈

移除资产

当一个资产移动到版本堆栈中时，它就成为该堆栈本身的次项。要将一个资产从版本堆栈中移出，您需要做的实际上就是将其重新设为堆栈所在文件夹的主项。

1. 通过调用 /v2/assets/:id 来 GET 版本堆栈本身
2. 获取堆栈本身的 parent_id（这将成为您的新目标文件夹 id）
3. 将您的目标资产按如下方式移动到该文件夹中：

调用：

POST https://api.frame.io/v2/assets/:parent_id/move

请求体：

1
{
2
    "id":"<asset_id>"
3
}

删除版本堆栈

删除版本堆栈非常简单：

DELETE https://api.frame.io/v2/assets/:version_stack_id/unversion

就是这样。删除堆栈会将其所有的组成资产返回到该堆栈所在的文件夹中。

从技术上讲，这一切都没问题——这个单例版本可以加载和播放，可以添加新版本，一切都会正常进行；但是，为了避免在 Frame.io Web 版及其他应用程序中给用户造成困惑，我们建议删除单例堆栈。

有关版本堆栈端点的更多信息，请参阅资产文档。