利用開始ガイド

Adobe Developer Console

Adobe API を使用する最初の手順は、Adobe Developer Console でプロジェクトを作成することです。Developer Console のプロジェクトは、Frame.io Developer API を使用するために構築するアプリケーションに相当します。これは、Frame.io 内のプロジェクトとは異なります。

Developer Console でプロジェクトを作成後、Frame.io API を追加します。

Frame.io V4 Developer API の新機能

Frame.io アプリケーションがバージョン 4 用に一新されたように、V4 API も新設計されました。一部の主要な概念はレガシーバージョンと似ていますが、より強力な共同作業ワークフローと統合をサポートするために、多くの概念が置き換えまたは再設計されています。まったく新しい API の導入は、運用を大幅に簡素化し、お客様の重要なワークフローを優先する機会となりました。

V4 API 内では、ワークスペース（レガシーバージョン の Frame.io では旧称が「チーム」）などの一部のリソースは、名前を変更し、Frame.io バージョン 4 と一致させました。一方、アセットなどのレガシーバージョンのその他のリソースは、開発者の混乱を軽減するために、特定のストレージエンティティ（ファイル、フォルダー、バージョンスタック）を参照するように名前を変更しました。また、カスタムフィールドや共有などの、まったく新しいリソースもあります。その他にも大幅な変更がある中で、リソース要求に対してデフォルトで返されるデータ量を大幅に削減し、応答の一部のプロパティ名を API サーフェス全体でより正確で一貫性のある名前に変更し、新しいカーソルベースのページネーションメカニズムに切り替えました。そのため、Camera to Cloud（C2C）API を除き、レガシー API と統合するクライアントは V4 API と互換性がないことを認識することが重要です。

さらに、一部の機能はまだ開発中であり、実際のお客様のユースケースとフィードバックに応じて迅速に対応し、進化させていく予定です。例としては、カスタムアクションやバージョンスタックを作成する機能が挙げられます。レガシー API で、利用可能だった機能がなくなったと思われる場合は、別の類似した機能があるか、まもなく利用可能となる場合があります。そのような場合は、お客様のご意見をお待ちしております。

V4 API の説明に進む前に、Frame.io バージョン 4 アプリケーションで示される重要な概念を説明します。まずは、Frame.io V4 ナレッジベースから始めましょう。アカウント、ユーザー、ワークスペース、プロジェクト、コレクション、共有、およびカスタムフィールド（メタデータ）などの概念は、V4 API で個別のリソースとしてモデル化されており、アプリケーションでのこれらの関係と機能を理解することは、V4 API でのその仕組みを理解するのに役立ちます。

API の概要

Frame.io V4 API は、RESTful アーキテクチャの原則に準拠するように設計されており、HTTP 標準メソッドとレスポンスコードを、一意のリソース固有の URL と共に使用します。Frame.io は、V4 API の OpenAPI 3.0 仕様 を公開しており、エンドポイント、要求パラメーター、およびレスポンスに関する詳細情報が記述されています。OpenAPI 仕様は、迅速なクライアントアプリケーション開発を促進するために、様々なサードパーティのコード生成ツールで使用できます。

URL とパスの表記法

OpenAPI 仕様で公開されている URL パスは通常、リソースの所有権と包含関係を反映します。そのため、一部の要求パラメーター（アカウント ID、フォルダー ID など）はリソースパス内に埋め込まれます。これらのパスは予測可能で理解しやすいように設計されていますが、API 要求によって返される一部の URL（事前署名されたアップロード URL や表示リンクなど）の構造は変更される可能性があるため、クライアントアプリケーションで直接作成しないでください。

要求クエリパラメーター

ページネーションの動作を制御し、関連リソースをレスポンスオブジェクトに含めるオプションの要求パラメーターは、クエリパラメーターの標準セットとして次のように定義されます：include, page_size, include_total_count一部の要求では、そのリソースまたは操作に固有の追加のクエリパラメーターがサポートされている場合があります。

1
GET https://api.frame.io/v4/accounts/{account_id}/folders/{folder_id}/children?&include=project&page_size=5&include_total_count=true

リクエストペイロードおよびレスポンスペイロード

リクエストペイロードとレスポンスペイロードはどちらも JSON オブジェクトとして構成されるため、HTTP POST、PUT、または PATCH 要求のコンテンツタイプヘッダーで application/json メディアタイプを指定する必要があります。リソースを作成または更新する場合、そのリクエストの data プロパティにリソースオブジェクトが含まれている必要があります。作成または更新されるリソースの属性は、このオブジェクト内に含まれています。同様に、リソースを含むレスポンスが成功した場合、そのレスポンスの data プロパティ内でこれらのリソースが提供されます。

ページネーション

結果セットのサイズが大きくなるにつれて、要求の待機時間を短縮するために、大量のリソースオブジェクト（フォルダーやコメントリストなど）を返す可能性があるレスポンスには、ページネーションが適用されます。これは、要求に対するレスポンスには、単一「ページ」の結果のみを含められることを意味します。前述のように、クライアントは要求を行うときに page_size クエリパラメーターを使用して最大 100 個以下の要素を含む特定のページサイズを選択できます。指定しない場合、ページサイズはデフォルトで 50 個の要素に設定されます。V4 API は、カーソルベースのページネーションと呼ばれるページネーションの形式を使用し、after クエリパラメーターに不透明な（クライアントはこの文字列を自分で構築しようとしない）カーソル文字列を含むレスポンスオブジェクトの links プロパティに相対リンクを含めます。これにより、クライアントは後続の要求を行うことで、次のページの結果を取得できます（以下のレスポンス例を参照）。現在、V4 API は一方向ページネーションのみをサポートしています。

1
{
2
    "data": [
3
        {
4
            "created_at": "2024-10-02T00:22:44.887775Z",
5
            "creator_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
6
            "file_size": 102432,
7
            "id": "df171f3e-c95f-4454-9071-825cd924b572",
8
            "media_type": "application/pdf",
9
            "name": "sample.pdf",
10
            "parent_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
11
            "project": {
12
                "created_at": "2024-08-21T17:45:41.881596Z",
13
                "description": "For demonstration purposes",
14
                "id": "976dd413-a92b-4af6-b465-98aded0174a8",
15
                "name": "Demo Project",
16
                "owner_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
17
                "root_folder_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
18
                "storage": 20881946,
19
                "updated_at": "2024-10-02T00:22:47.168489Z",
20
                "workspace_id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
21
            },
22
            "project_id": "976dd413-a92b-4af6-b465-98aded0174a8",
23
            "status": "created",
24
            "type": "file",
25
            "updated_at": "2024-10-02T00:22:44.927993Z"
26
        }
27
    ],
28
    "links": {
29
        "next": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/folders/e183c7ba-07d9-425a-9467-ebdf0223d9ce/children?after=g3QAAAACZAAGb2Zmc2V0YQVkAAR0eXBlZAANb2Zmc2V0X2N1cnNvcg%3D%3D"
30
    },
31
    "total_count": 21
32
}

エラー

エラーが発生した場合、レスポンスオブジェクトの errors プロパティには、発生したエラーの詳細を示す 1 つ以上のエラーオブジェクトの配列が含まれます。現時点では、バッチ操作は V4 API ではサポートされていないため、部分的な成功やエラーをクライアントが処理しなければならないケースはありません。

1
{
2
    "errors": [
3
        {
4
            "detail": "Unexpected field: foo",
5
            "source": {
6
                "pointer": "/data/foo"
7
            },
8
            "title": "Invalid value"
9
        }
10
    ]
11
}

次の表に、V4 API で使用される一般的なステータスコードを示します。

認証および認可

V4 API は、OAuth 2.0 と Adobe Identity Management Server（IMS）を使用してユーザー（AuthN）を認証し、そのユーザーに代わってアクセストークンを生成します。アクセストークンは、HTTP Authorization ヘッダー（ベアラートークン認証）を介して各 API 要求に提供される必要があります。

バージョンと下位互換性

Frame.io V4 API は、以前のバージョンの Frame.io API と下位互換性がありません。V4 の概念とデータモデルに大幅な変更が適用されたため、Frame.io V4 API は通常、レガシーアカウントに含まれるリソースへのアクセスや更新には使用できません。そのため、V4 API に関連付けられた URI にはすべて /v4 パスプレフィックスが含まれています。ただし、V4 API は現在も急速に進化しており、新機能によっては、破壊的変更が必要になる場合があります。Frame.io では、API に対する新しい追加機能がリリースされます。これは、一定期間試験的に行われるもので、お客様からのフィードバックや使用状況の指標を受け取り、それに応じた対応を行うことができます。当社では、アップタイム要件の高い本番品質の統合を管理するお客様にとって、下位互換性は大きな懸念事項であることを認識しており、カスタム HTTP ヘッダーを介して追加レベルのバージョン管理をサポートできるよう V4 API を設計しています。これにより、クライアントは実験的なエンドポイントの使用を選択することで破壊的な変更を回避し、V4 ネームスペース内で下位互換性を保証できます。詳細は近日中に発表されますが、現時点では、V4 API の初期リリースは安定しており、アドビが破壊的変更の導入を検討するまでにはしばらく時間がかかると想定しても安全です。

レート制限

すべての V4 API 呼び出しはレート制限されており、各 API リソースと操作は独自の制限で構成されています。制限は、1 分あたりの最大要求数が 10 から、1 秒あたりの最大要求数が 100 までの範囲です。現時点では、各制限はアカウントによって適用されますが、今後、ポリシーと制限自体が変更される可能性があります。

V4 API は、プログレッシブレート制限の「リーキーバケット」アルゴリズムを使用しています。この戦略では、割り当てられたタイムウィンドウ中に更新を徐々に制限します。言い換えると、特定のリソースの更新を制限した後のハードカットオフ（つまり、「固定」および「スライディングウィンドウ」施行戦略）の概念はありません。代わりに、残りの制限は、リソースの制限およびタイムウィンドウを基準にしたペースで常に更新されます。特定のエンドポイントのレート制限を超える要求は、429 HTTP エラーで失敗します。

429 エラーに対応するために推奨される戦略は、通常、「指数バックオフ」と呼ばれます。 つまり、

• 429 を受信した場合、要求を再試行する前に一定時間（1 秒以上）一時停止する
• さらに 429 が受信された場合は、通常の機能が再開するまで以前の待機時間を指数関数的に、または 2 倍に増やす

特定の要求に適用されるレート制限を決定するために、クライアントはレスポンスで返された次の HTTP ヘッダーを検証できます。

API の詳細

V4 API の最も信頼できるドキュメントは API リファレンスガイドですが、最初の要求を発行する前に、V4 API によってモデル化されたリソース階層を理解しておくと役立ちます。

リソース階層

アカウントは通常、組織に関連付けられており、サブスクリプションプラン、コンテンツ所有権、ユーザーロール / 権限、ワークスペース組織を決定する基本的なリソースを表します。そのため、V4 API のほぼすべてのエンドポイントへの URL パスには、リソースが存在するアカウントを識別するプレフィックスが含まれています。

ワークスペース（レガシーバージョン の Frame.io では旧称が「チーム」）とプロジェクトは、誰がどのコンテンツにアクセスできるのかを含め、コンテンツとユーザーの両方を整理するために使用されます。

Frame.io 内のコンテンツリソースの基本的な階層は次のとおりです。

Frame.io にアップロードされたすべてのアセットは最終的にはファイルとして表示されますが、フォルダーおよびバージョンスタックはコンテナーとして機能するストレージリソースであり、バージョン管理されたアセットをサポートする階層型ストレージモデルの基盤を提供します。大部分のユーザーは、Frame.io 内のフォルダーの基本的な概念に既に精通していると思います。フォルダーは、単にその他のストレージリソースの順序付けされていないコンテナーとして機能し（children としてモデル化される）、フォルダーツリー内のノードを表します。すべてのプロジェクトには一意のルートフォルダー（root_folder_id キーで識別）があり、プロジェクトのすべてのアセットが存在するフォルダーツリーのルートとして機能します。

バージョンスタックは、ファイルの順序付けされたコンテナーです。順序は厳密に直線的であり、これによりそれぞれの子のバージョン番号が決定しますが、クライアントはバージョンスタック内のファイルを適切に並べ替えることができます。ファイルは、常に正確に 1 個のフォルダーまたはバージョンスタックの子（内に含まれる）になります。同様に、フォルダーまたはバージョンスタックは、常に正確に 1 個のフォルダー（プロジェクトのルートフォルダーを除く）の子になります。

Frame.io 内に保存されているファイルとフォルダーに関する基本的な CRUD 操作実行の詳細については、API リファレンスガイドを参照してください。現状では、V4 API はフォルダーのコンテンツを一覧表示するときにバージョンスタックのみをサポートしていますが、バージョンスタックを作成および更新するためのエンドポイントは近日中に提供される予定です。

SDK

SDK は TypeScript と Python で使用できます。以下のコマンドを使用してインストールできます。ドキュメントの「SDK リファレンス」セクションには、Python および TypeScript SDK の完全なリファレンスが記載されています。

TypeScript

$
npm i -s frameio

npm での表示

Python

$
pip install frameio

PyPi での表示

Postman を使用して開発を開始

Postman は、web 開発者が API のテストや操作に使用する一般的なツールです。このセクションでは、V4 API で使用するための Postman の設定の基本について説明します。このセクションには、開発者がすぐに使用を開始できる事前構築済みの Postman コレクションが含まれています。

前提条件

Postman コレクションの読み込み

Frame.io Developer API コレクションには、すべての V4 API パブリックエンドポイントが含まれています。このデフォルト環境は、Postman 内でフォークまたは複製できるテンプレートです。これを使用して、テスト用のユーザー固有の環境変数を設定するか、直接更新することもできます。

コレクションをダウンロードして、コレクションと環境が読み込まれると、Postman 内にその両方が表示されます。環境には、BASE_URL 変数と IMS_BASE_URL 変数のデフォルト URL が含まれています。追加の環境変数は空であり、特定の入力が必要です。

認証の設定

IMS_CLIENT_ID および IMS_CLIENT_SECRET の環境変数は、Adobe Developer Console のプロジェクトに関連付けられている認証情報ページから取得した値に設定する必要があります。

これらの環境変数を設定したら（これらの変更は必ず実際の環境に保存してください）、次の手順は Postman のコレクションブラウザーで Frame.io V4 Developer API コレクションのルートを選択し、認証設定に移動することです。ダイアログの下部にある「新しいアクセストークンを取得」ボタンをクリックすると、新しいブラウザーウィンドウ / タブが開き、Adobe IMS で認証するように求められます。認証されると、ブラウザーは Postman にリダイレクトされ、受信したベアラートークンが保存されます。このトークンは、入力後にダイアログのトークンフィールドのすぐ下にある「更新」リンクをクリックすると更新できます。

認証設定が正常に完了したことを確認するには、Postman コレクションブラウザーの「ユーザー」の下にある「GET me」エンドポイントを選択し、「送信」をクリックします。正しく設定され、ユーザー認証が成功した場合は、認証されたユーザーに関する基本情報を含む 200 レスポンスが表示されます。

ワークスペースおよびプロジェクトの取得

V4 API を使用して操作するリソースのほとんどは、プロジェクト内に含まれています。プロジェクトはワークスペース内で整理および管理されるため、プロジェクトを作成または一覧表示する最初の手順は、プロジェクトを含むワークスペース ID を決定することです。ログインしたアカウントでアクセスできる既存のワークスペースの一覧を取得するには、Postman コレクションブラウザーで LIST workspaces エンドポイントを選択し、「送信」ボタンをクリックします。ACCOUNT_ID 環境変数が適切に設定されている場合は、使用可能なすべてのワークスペースの一覧を含むレスポンスが返されます。

操作するワークスペースを特定したら、その id プロパティの値を WORKSPACE_ID 環境変数にコピーして、環境を保存します。これで、そのワークスペース内でアクセスできるプロジェクトの一覧を要求する準備ができました。Postman で LIST projects エンドポイントを選択し、「送信」をクリックします。レスポンスには、ワークスペース内に含まれるプロジェクトの一覧が含まれます。試してみるプロジェクトを特定し、その id 値を現在の Postman 環境の PROJECT_ID 環境変数にコピーします。また、root_folder_id プロパティを環境内の FOLDER_ID プロパティにコピーします。プロジェクト内のアセットツリーで操作する場合、多くの要求はリソースの親フォルダー ID をパスパラメーターとして受け取ります。この環境変数をルートフォルダーを参照するように設定すると、プロジェクトのルートレベルに含まれるリソースに対して操作を要求できます。

プロジェクトのコンテンツの一覧表示

FOLDER_ID がプロジェクトのルートフォルダーに設定されたので、プロジェクト内に保存されているコンテンツを一覧表示できるようになります。「list folder children」エンドポイントを選択し、「送信」ボタンをクリックして試してみます。これは、リソースの一覧を返す GET 要求に含めることができるオプションのクエリパラメーターをいくつか試してみる良い機会となります。以下の例では、返されるリソースの数を 5（page_size=5）に制限し、子リソースの合計数を含め（include_total_count=true）、子リソースの作成者に関する情報を含める（include=creator）クエリパラメーターが追加されています。各エンドポイントでサポートされているクエリパラメーターの詳細については、API リファレンスガイドを参照してください。

新しいファイルのアップロード

ファイルを Frame.io プロジェクトにアップロードするには、2 つ以上の要求が必要です。CREATE file エンドポイントを選択して、Frame.io プロジェクトでファイルアセットを作成する方法を示します。POST リクエストの本文には、アップロード先ファイル名、メディアタイプ、およびファイルサイズを記述するリソースが含まれます。要求が成功すると、アップロード先フォルダーにコンテンツが含まれないプレースホルダーのファイルリソースが作成されます。新しいファイルリソースの status プロパティは「作成済み」に設定され、ファイルは 0 バイトとなり、アップロードが開始されていないことを示します。 レスポンスには、後続の要求でファイルのコンテンツをアップロードできる事前署名済み URL で構成される 1 つ以上の upload_urls も含まれます。upload_urls 配列に返される事前署名済み URL の数は、元のファイルのファイルサイズに基づいて決定されます。

Postman での試験中は、アップロードプロセスを簡素化するために、比較的小さなファイル（10 MB 未満）を選択すると、必要となるアップロード URL が 1 個のみとなり、非常に便利です。ソースファイルを必要な数のチャンクに分割する小さなシェルスクリプトを記述し、より大きなファイルをアップロードするために同じ数の後続要求を発行するのも簡単です（上記および以下の例を参照）。後続のアップロード要求の送信について、以下にいくつかの重要な詳細情報を示します。

すべてのパートがそれぞれのアップロード URL にアップロードされると、Frame.io メディアパイプラインは自動的にパートをつなぎ合わせ（複数ある場合）、アップロードを処理（適切なトランスコーディングの実行、サムネイルの生成、レンディションのプレビューなど）、進行中または保留中の操作を反映するようにファイルの status を更新します。ファイルのサイズによっては、Frame.io web アプリケーションが更新されてファイルのアップロード状態が反映されるまでに時間がかかる場合があります。