ファイルツリーの読み取り

概要

最終目標がワークフローのステージを通じたアセットの公開、編集、プッシュのいずれであるかにかかわらず、Frame.io との多くのより緊密な統合には、ユーザーコンテキスト、最終的にはディレクトリ表示の列挙が必要となります。

Frame.io 内のリソース（またはファイル）の基本的な階層は、次のとおりです。

アカウント／チーム／プロジェクト／アセット

この記事では、順次 API 呼び出しを行うことでファイルツリーを操作する方法について説明します。 ファイルを操作するための一般的な戦略は、まずプロジェクトにアクセスし、フォルダーを列挙してから、その中に含まれているアセットおよびバージョンスタックを操作することです。

重要な概念

各プロジェクトには固有のルートアセットがあります

RESTful API は通常、一意の識別子を使用してリソースを記述します。root_asset_id は、プロジェクトのアセットツリーの一意の識別子です。プロジェクトのルートノードとして機能する特別な構造として扱ってください。残りのアセットは、下方向のツリーのルートの下にスタッキングします。 一般的なワークフローでは、API ユーザーは、ファイル階層のより深いアセットを操作するには、ツリーを降りる必要があります。

共同作業者と共有プロジェクト

共同作業者は、Frame.io の重要なユーザーロールです。このようなユーザーは、プロジェクトワークスペースにアクセスできますが、そのプロジェクトの包括的なアカウントに属していない場合があります。

共同作業者とチームメンバーの権限が異なることを除外すれば、主な違いは、共同作業者のメンバーシップは厳密にプロジェクトに限定され、チームとは関係がない場合があることです。 **

これにより、ディレクトリリストが最も重要なワークフローに小さな問題点が生じます。 上記の基本的な階層（アカウント／チーム／プロジェクト／アセット）は、ほとんどのユースケースに機能する一方、認証されたユーザーが共同作業者であるが、チームメンバーではないプロジェクトを記述しません。 ディレクトリをリストするときにこれを回避するには、次のいずれかを行うことができます。

• ユーザーの共有プロジェクトを取得し、チームおよびアカウント階層を展開し、すべてをまとめて圧縮するか、または
• ユーザーの共有プロジェクトを取得し、そのすべてを個別のコンテキストとしてまとめてリストします。

いずれの方法でも問題ありません。後者のほうが少し簡単ですが、前者のほうが Frame.io の web アプリが同様の情報を表示する方法に近くなります。いずれにせよ、このガイドで記載されている方法は両方に適用されます。

ディレクトリのリスト

1.ユーザーのアカウントの取得

GET https://api.frame.io/v2/accounts

有効なベアラートークンで上記の呼び出しを行い、ユーザーのアカウントを取得します。 ユーザーがチームメンバー、チームマネージャーまたは管理者ステータスを持つすべてのアカウントを受け取ります。 また、ユーザーが請求／管理者権限を持っていても、チームアクセス権がないチームを受け取る場合もありますが、これはまれであり、次のステップで除去されます。

アカウントリクエストのペイロードはかなり冗長です。応答から取得できる重要なデータの要約は、次のとおりです。

• id
• display_name
• owner（email、name）
• （オプション）image

id および owner.email のみがユーザーアカウントの必須フィールドであることに注意してください。 別のアプリでユーザーを表示する場合は、ユーザーアカウントを表示するための条件ロジックを作成することを検討します。確認し、null でない場合は、次の優先順位でアカウントを表示することをお勧めします。 **

1. 「display_name」
2. 「owner.name のアカウント」
3. 「owner.email のアカウント」

ユーザーがアカウントを選択したら、追加の API リクエストが必要なチームを表示したくなる場合があります。

2.アカウント内のチームの取得

GET https://api.frame.io/v2/accounts/{{account_id}}/teams

Frame.io 内のチームは、「パブリック」（アカウント内のチームメンバーが発見可能）の場合もあれば、「プライベート」（特定のチームメンバーのみが発見可能）の場合もあります。 API がコンテキストを処理するので、必要なことは、上記のリクエストで account_id を指定して有効な呼び出しを行うだけです。

ページネーションについて詳しくは、「ページネーションとエラーを参照してください。

各チームから、次の属性を取得します。

• id
• name
• （オプション）team_image

チームが選択されたら、その構成プロジェクトを表示できます。

メモ：必要に応じて、ユーザーについて GET https://api.frame.io/v2/teams することもできます。アドビの API は、アカウントコンテキストに関係なく、ユーザーが属しているすべてのチームを返します。これは、技術的には機能しますが、ユーザーは、次のような別のステップを実行しない限り、コンテキストを失う恐れがあります。

1. 各チームの横にアカウント名を反映することで、コンテキストを再設定
2. ユーザーがリストのテキストを検索できるようにする

アカウントレベルから共有プロジェクトを下にリストする場合は、GET https://api.frame.io/v2/projects/shared への追加の呼び出しを行う必要があります。応答で返された各プロジェクトには、次の属性が含まれています。これらの属性は、ディレクトリの構築時に継承できます。

• （プロジェクト自体の）id
• team_id
• team.account_id

または、選択したアカウントコンテキストに「チーム」として追加するだけで、「共有プロジェクト」のアフォーダンスを作成できます。それを行うことを選択した場合、共有プロジェクトを真のチームスコープのプロジェクトから視覚的に分離すると、エンドユーザーにとって便利です。単一の共有プロジェクトリストには、様々な真のアカウントおよびチームコンテキストが含まれる場合があるためです。

3.チームのプロジェクトの取得

GET https://api.frame.io/v2/teams/{{team_id}}/projects

次に、上記の呼び出しを行い、チーム内のすべてのプロジェクトを取得します。

プロジェクトごとに、次を取得します。

• id
• name
• root_asset_id
• （オプション）private（UI でユーザーを区別する場合）

記事の冒頭で説明したように、root_asset_id は、Frame.io のリソースアーキテクチャの重要な部分であり、それで、プロジェクト内のファイルおよびフォルダーディレクトリをナビゲートできます。

| * アカウント | * チーム | * チームプロジェクト（および root_asset_ids） | * 共有プロジェクト（および root_asset_ids） | アセットを作成または取得するために必要なのはこれだけです。

フォルダーとアセットのリスト

4.初期フォルダー構造の構築

GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder

これにより、プロジェクト内のすべてのフォルダーが root_asset_id から順に列挙されます。 フォルダーがない場合は、空のリストが返されます。ファイルとフォルダーの両方を含める場合（例えば、次のステップが Frame.io からのアセットの GET になる場合）は、クエリ文字列パラメーターを省略してください。

type パラメーターで使用可能な他の 2 つのフィルターオプションは、file および version_stack です。3 つのフィルターはすべて、互いに排他的であり、フィルタリングされていない呼び出しは、3 つの type をすべて組み合わせて返します。

5.ディレクトリツリーの分析

戻ってくるフォルダーごとに、次をキャプチャすることが必要になります。

• id
• name

各フォルダーはアセットであるので、フォルダー構造を分析するためのワークフローは次のようになります。

1. GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder
   1. リストでフォルダー名をレンダリング
   2. ユーザーがフォルダーをクリックしたとき、フォルダーの id を次のクエリに渡す
2. GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder

6.作成とアップロード

フォルダーへ： POST https://api.frame.io/v2/{{folder_id}}/children

アップロードするフォルダーの id を用意したら、リソースドキュメントおよびガイドに従って、その子への POST を行います。これにより、プレースホルダーアセットが作成され、（選択したメソッドに応じて）次が返されます。

• ユースケースのトラッキングを目的とした uuid
• ファイルを Frame.io のバックエンドデータストレージに直接、PUT するために使用できる upload_urls のリスト

バージョンスタックへ： バージョンスタックは、同様のワークフローを提示しますが、このガイドで記載されているステップが 1 つ追加されています（以下に概要を示します）。重要であるのは、バージョンスタックは、アセットのように見えるが、フォルダーのように動作するコンテナであること、および、まずアセットをアップロードしてから、別のアクションとしてバージョンスタックにスタッキングする必要があることを覚えておくことです。

したがって、アセットをバージョンスタックにアップロードするには、次が必要になります。

• バージョンスタックの id
• バージョンスタックの parent_id（例えば、その格納フォルダーまたはプロジェクトルート）

まず、POST https://api.frame.io/v2/assets/{{parent_id}}/children して、新しいアセットを作成します。応答の新しい id をキャプチャします。

これで、新しいアセットの id を使用し、POST https://api.frame.io/v2/assets/{{version_stack_id}}/version できるようになりました。本文ペイロードは、次のとおりです。

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