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

概要

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

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

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

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

主要な概念

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

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

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

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

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

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

必要なスコープ

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

バージョンスタックへのアセットの追加

ステップ 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. 新しいアセットをアップロードする場合は、アセットの作成時に成功応答で返された id を使用します。
2. 既存のアセットをスタッキングする場合は、上記のプロセスを介して id を知る必要があります。

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

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

ステップ 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

本文：

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 アプリケーションやその他のアプリケーションでユーザーに混乱を招くシナリオを示さないよう、シングルトンスタックは削除することをお勧めします。

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