> This page is for プラットフォーム, version レガシー.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://developer.frame.io/platform/v4/llms.txt
> - V4 Experimental: https://developer.frame.io/platform/v4-experimental/llms.txt
> - レガシー: https://developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.frame.io/_mcp/server.

# バージョンスタックの管理

## 概要
バージョンスタックは、Frame.io の整理原則であり、アセットをフォルダーに配置せずに縦に「スタック」できるようにします。スタックされたバージョンにより、Frame.io UI 内でのアセット間のナビゲーションが容易になり、左右に並べたレビューがサポートされます。

スタックへの直接のアップロードは現在、サポートしていないので、基本的なバージョンスタックワークフローを管理するための API シーケンスは、Frame.io UI と同じシーケンスに従います。

1. アセットをアップロード（オプション：プライベートとしてマーク）する
2. アセットをスタックに割り当てる

既存のバージョンスタックの順序を変更したり、個々のバージョンをスタックからノックアウトしたりできます。最後に、バージョンスタックは、構成アセットを削除せずに削除できます。

<Info title="すべてのバージョンスタックには cover_asset があります">
バージョンスタックの最上位レベルには、必ず `cover_asset_id` という属性があります。これは、Frame.io web UI にサムネイルが表示されているアセットの `id` であり、スタック内で最も大きい番号のバージョンです。
</Info>

### 主要な概念
**バージョンスタック** - **フォルダー**と同様 - アセットの特別な `types` です。同じエンドポイントでこれを取得し、API 応答の `type` キーの値に基づいて解析し、それに応じてルーティングできます。これは、実際には一般的に簡単ですが、大規模なスタックを管理する場合は、いくつかの問題点を提示する可能性があります。

バージョンスタックを操作するための鍵は、**最も一般的な 4 つのシナリオ**を分離することです。

1. アセットをアセットに追加すると、新しい `id` のスタックが作成されます。
2. アセットは既存のスタックに追加できます。
3. スタックは並べ替えることができます。
4. 個々のバージョンは削除できます。

**最初の 2 つのシナリオ**では、同じ[エンドポイント呼び出し](ref:post_assets-assetid-version)を使用するため、唯一の本当の微妙な違いは、（2 つのアセットから）新しいスタックを作成するか、アセットを既存のスタックに追加するかを知ることです。それとは別に、制約は、次のように予測可能です。

1. スタックは、`asset_type` で一致する必要があります（例えば、画像をストリームにスタッキングすることはできません）。 ** **
2. 代行ユーザーは、ソースアセットと宛先アセットまたはスタックの両方に対する権限を持っている必要があります。
3. アセットは、順番にスタッキングされます。
4. スタックをスタックにスタッキングすることはできません。
5. フォルダーはすぐに表示されます。

**後者の 2 つのシナリオ**も非常に単純ですが、スタック自体についてもう少し詳しく知る必要があります。例えば、スタック内のアセットを並べ替えるには、ターゲットアセットを配置する場所の両側にあるアセットの `id` がわかっている必要があります。これは一般的に、スタック全体を既に取得していることを意味します。

### 必要なスコープ
このガイドを開始する前に、次のスコープを含むトークンがあることを確認する必要があります。

| スコープ| 理由|
|----------|----------|
| **アセット：**読み取り、更新| \- ソースおよび宛先アセットを取得します。<br />- アセットをバージョンスタックに追加します。<br />- スタックを並べ替えます。<br />- スタックからアセットを削除します。<br />- スタックを削除します。|

## バージョンスタックへのアセットの追加
### ステップ 1：宛先の特定
最初のステップは、2 つの重要なシナリオ（アセットを別のアセットに追加してスタックを作成するか、アセットをスタックに追加してそのスタックを拡張するか）のうち、いずれのシナリオにいるかを特定することです。

バージョン管理されていないアセットを操作することがわかっている場合、またはバージョンスタック `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. 新しいアセットをアップロードする場合は、[アセットの作成](ref:post_assets-parentid-children)時に成功応答で返された id を使用します。
2. 既存のアセットをスタッキングする場合は、上記のプロセスを介して `id` を知る必要があります。

バージョンスタック追加に必要な本文パラメーターは、`next_asset_id` です。

```json
{
    "next_asset_id": "<source-asset-id>"
}
```
### ステップ 3：ソースアセットを宛先に追加
両方のアセット `id` パラメーターがわかったので、`/assets/:id/version` に `POST` する準備ができました。ここで、:id は宛先アセットまたはバージョンスタックであり、ソース（新しい）アセットは本文ペイロードにあります。

## バージョンスタックの並べ替え
バージョンスタックは、各アセットが `next_asset_id` および `prev_asset_id` 近傍にあるというシンプルな序数概念に依存しています。この順序は、バージョン番号付けではなく、各アセットの `index` 属性を参照しています。`index` は、バージョン番号とは逆に進むので、次のようになります。
* スタック内の最初の（最も低い番号の）バージョンには、`prev` アセットはありますが、`next` アセットはありません
* スタック内のより新しい（最も高い番号の）バージョンには、`next` アセットはありますが、 `prev` アセットはありません
* すべての「内部」バージョンには、`prev` および `next` アセットがあります。これらはそれぞれ、より高いバージョン ID を持つアセット、より低いバージョン ID を持つアセットです。

これにより、次の 3 つの異なるシナリオが得られます。これらはすべて、同じエンドポイント呼び出しに依存します。

**呼び出し：**
```
PUT https://api.frame.io/v2/asset/:id/tween
```
**本文：**
```json
{
  "prev_asset_id": "<asset_id>",
  "next_asset_id": "<asset_id>"
}
```

いずれの場合も、URL パスの `id` は、移動するアセットになります。

| シナリオ| `prev_asset_id`| `next_asset_id`|
|----------|----------|----------|
| スタックの一番上に移動| `null`| 前の最上位アセット（最も高いバージョン番号）の `id`。|
| スタックの一番下に移動| 前の最下位アセット（v1）の `id`。| `null`|
| スタック「内部」でバージョンを移動| アセットの移動先のすぐ上にあるアセットの `id`。 **| アセットの移動先のすぐ下にあるアセットの `id`。 **|

## アセットの削除とバージョンスタックの削除
### アセットの削除
アセットは、バージョンスタックに移動されると、スタック自体の子になります。アセットをバージョンスタックから移動するには、スタックの格納フォルダーに実質的に再親化することが必要になります。

1. `/v2/assets/:id` への呼び出しを介してバージョンスタック自体を `GET`
2. スタック自体の `parent_id` を取得します（これが、新しいターゲットフォルダー `id` になります）。
3. 次のように、ターゲットアセットをフォルダーに移動します。

**呼び出し**：
```
POST https://api.frame.io/v2/assets/:parent_id/move
```
**本文**：
```json
{
    "id":"<asset_id>"
}
```

### バージョンスタックの削除
バージョンスタックの削除は、非常に簡単です。

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

これで完了です。スタックを削除すると、そのすべての構成アセットがスタックの格納フォルダーに返されます。

<Info title="サイズ 1 のスタックは削除してください">
バージョンスタックからすべての要素を削除すると、要素が 1 個のバージョンスタックになります。これは簡単に見つけることができます。`id` を使用してバージョンスタックを `GET` すると、`&quot;version&quot;: 1` 属性を持っていることがわかります。
</Info>
これは技術的には問題ありません。シングルトンバージョンが読み込まれて再生され、新しいバージョンを追加でき、すべてが普通に実行されますが、Frame.io の web アプリケーションやその他のアプリケーションでユーザーに混乱を招くシナリオを示さないよう、シングルトンスタックは削除することをお勧めします。

バージョンスタッキングエンドポイントについて詳しくは [アセット](ref:assets)ドキュメントを参照してください。