Frame.io レガシー API から V4 への移行ガイド

利用開始

Frame.io V4 API は、V2 エンドポイントまたは Frame.io V3 API としてよく呼ばれるレガシー API の完全な再設計です。この再設計では、Frame V4 の新機能を最大限に活用しており、下位互換性はありません。このガイドでは、レガシー API と V4 API の主な違いについて説明し、スムーズな移行に役立つステップバイステップのガイダンスを提供します。

主な違い

API 管理

V4 API は、Adobe Developer Console を介して管理されますが、レガシー API は Frame.io 開発者サイトで管理されます。

リソース構造

アセット → フォルダーとファイル：レガシーの統合されたアセットエンドポイントとは異なり、V4 のファイルとフォルダーの個別のエンドポイント。

認証

V4 API は、OAuth2.0（authorization_code 付与タイプ）をサポートしています。

機能パリティ

一部の特殊なレガシー呼び出しは、V4 ではまだサポートされていません。

モデルの共有

レビューリンクとプレゼンテーションリンク → 共有リンク：V4 では、レビューリンクとプレゼンテーションリンクが単一の「共有リンク」に統合され、様々なカスタムブランディングオプションがサポートされています。

チーム構造

チーム → ワークスペース：レガシー API の「チーム」エンドポイントは、V4 では「ワークスペース」エンドポイントに置き換えられました。

移行チェックリスト

既存の API 呼び出しの監査

既存の API 呼び出しを監査します。既存の呼び出しを以下の表と比較します。使用するエンドポイントがこの一覧に含まれていない場合は、V4 ではまだ存在していません。このフォームからフィードバックを送信してください。

Oauth2.0 の実装

Adobe Developer Console を使用して、OAuth2.0 を実装します。レガシー Frame.io 開発者トークンと [developer.frame.io](http://developer.frame.io/] で管理されている既存の OAuth アプリは、Adobe Admin Console で管理されている V4 アカウントでは機能しません。

注意：Adobe Admin Console で管理されていない V4 移行済みアカウントの場合、既存の開発者トークンは引き続き機能するため、手順 3 に進むことができます。

リファクタリングコード

**コードをリファクタリングします。**新しい V4 API ルートと JSON ペイロード（ファイル / フォルダーとアセットなど）を使用します。

徹底したテスト

**徹底的したテストを実行してください。**アップロード、コメント、Webhook に重点を置いて、V4 アカウントを使用してテストします。

レガシーコードの削除

**レガシーコードパスを削除します。**レガシー API エンドポイントを利用するすべてのコードパスは V4 で失敗するため、削除します。

専用ログインの実装

認証 URL がそれぞれ個別であるため、V4 専用のログイン方法を実装します。V4 認証 URL はレガシー API とは異なり、レスポンスでレガシーアカウントは返されないため、個別の統合として扱う必要があります。

この一覧は、レガシー API と V4 API の直接的な相関関係を網羅しているわけではありません。新しいエンドポイントがリリースされるたびに定期的に更新されます（試験的バージョンを使用する場合があります）。ここに記載されていないエンドポイントについてご質問がある場合は、サポートチーム support@frame.io までお問い合わせください。

認証

アドビプロジェクトの作成

Adobe Developer Console でプロジェクトを作成し、Frame.io を製品として追加します。

認証タイプの選択

**認証を行います。**詳細については、認証ガイドを参照してください。V4 アカウントが Adobe Admin Console でまだ管理されていない場合は、この手順をスキップできます。

ユーザー認証：クライアント ID やクライアントシークレットを使用して Frame に接続します。ユーザーはユーザー名とパスワードを使用してログインする必要があります。
サーバー間認証：クライアント ID とクライアントシークレットを使用して Frame に接続しますが、ループ内のユーザーがブラウザー経由でログインする必要はありません。

ベアラー認証の実装

JWT ベアラー認証：API 要求ごとに、Authorization キーと Bearer <IMS_ACCESS_TOKEN> の値を含むヘッダーを介して認証トークンを渡します。

エンドポイントマッピング（レガシー API から V4）

次の表には、同等の V4 を持つレガシー API エンドポイントのみが含まれています。レガシー API 呼び出しがここに表示されない場合は、直接移行パスがないため、廃止されている可能性があります。

1.アカウントとユーザー情報

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
GET	`/v2/accounts` （ユーザーのアカウントを取得）	GET	`/v4/accounts` （アカウントを一覧表示）	V4 は、ユーザーがアクセスできるすべてのアカウントを返します。
GET	`/v2/accounts/{account_id}`	GET	`/v4/accounts/{account_id}`	V4 に存在しません特定のアカウントに関する情報を取得します。V4 では、「チーム」への参照は「ワークスペース」に置換されます。
GET	`/v2/me`	GET	`/v4/me`	現在のユーザーのプロファイルを取得します。

2.ワークスペース（チームエンドポイントを置換）

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
GET	`/v2/accounts/{account_id}/teams` （アカウントのすべてのチームを取得）	GET	`/v4/accounts/{account_id}/workspaces` （ワークスペースを一覧表示）	レガシー API 概念の「チーム」 → V4 の「ワークスペース」。
POST	`/v2/accounts/{account_id}/teams` （指定されたアカウントのチームを作成）	POST	`/v4/accounts/{account_id}/workspaces` （ワークスペースを作成）	本文が類似しています（名前など）。レスポンスはチームオブジェクトではなくワークスペースオブジェクトです。
GET	`/v2/teams/{team_id}` （チームを取得）	GET	`/v4/accounts/{account_id}/workspaces/{workspace_id}` （ワークスペースを表示）	チーム ID → V4 のワークスペース ID。
GET	`/v2/teams/{team_id}/members` （チームメンバーを取得）	GET	`/v4/accounts/{account_id}/workspaces/{workspace_id}/users` （ワークスペースメンバーを取得）	ワークスペース内のすべてのユーザーを返します（試験的 API で使用可能）
POST	`/v2/teams/{team_id}/members` （チームメンバーを追加）	PATCH	`/v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id}` （ワークスペースでのユーザーロールの追加または更新）	ワークスペースでユーザーを追加または削除できます（試験的 API で使用可能）

3.プロジェクト

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
GET	`/v2/teams/{team_id}/projects` （チーム別にプロジェクトを取得）	GET	`/v4/accounts/{account_id}/workspaces/{workspace_id}/projects` （プロジェクトを一覧表示）	V4 で `account_id` と `workspace_id` の両方を指定する必要があります。
POST	`/v2/teams/{team_id}/projects` （プロジェクトを作成）	POST	`/v4/accounts/{account_id}/workspaces/{workspace_id}/projects` （プロジェクトを作成）	本文が類似しています。`{ "name": "MyProject", ... }`。
GET	`/v2/projects/{project_id}` （ID 別にプロジェクトを取得）	GET	`/v4/accounts/{account_id}/projects/{project_id}` （プロジェクトを表示）	`account_id` および `project_id` が必要です
PUT	`/v2/projects/{project_id}` （プロジェクトを更新）	PATCH	`/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}` （プロジェクトを更新）	V4 は部分的な更新に PATCH を使用します。
DELETE	`/v2/projects/{project_id}` （ID 別にプロジェクトを削除）	DELETE	`/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}` （プロジェクトを削除）	プロジェクトを削除します。
GET	`/v2/projects/{project_id}/collaborators` （プロジェクト共同作業者を取得）	GET	`/v4/accounts/{account_id}/projects/{project_id}/users`	プロジェクト内のすべてのユーザーを返します（V4 試験的 API で使用可能）
POST	`/v2/projects/{project_id}/collaborators` （プロジェクトへの共同作業者の追加）	PATH	`/v4/accounts/{account_id}/projects/{project_id}/users/{user_id}`	プロジェクトでユーザーを追加または削除できます（V4 の試験的 API で使用可能）

4.フォルダー

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
GET	`/v2/assets/{asset_id}/children` （子アセットを取得）	GET	`/v4/accounts/{account_id}/folders/{folder_id}/children` （フォルダーの子を一覧表示）	レガシー API の `asset_id` がフォルダーであった場合は、V4 で `folder_id` になります。
POST	`/v2/assets/{parent_asset_id}/children` （アセットを作成）	POST	`/v4/accounts/{account_id}/folders/{folder_id}/folders` （フォルダーを作成）	レガシー API では `"type": "folder"` を使用しましたが、V4 では `{"data": {"name": "Folder name"}}` を使用します。
GET	`/v2/assets/{asset_id}` （アセットを取得）	GET	`/v4/accounts/{account_id}/folders/{folder_id}` （フォルダーを表示）	レガシー API には「タイプ」：「フォルダー」が必要となります。 V4 API では、パスパラメーターで `folder_id` と `account_id` が必要です
PUT	`/v2/assets/{asset_id}`（アセットを更新）	PATCH	`/v4/accounts/{account_id}/folders/{folder_id}` （フォルダーを更新）	レガシー API：`asset_id` はフォルダー ID になります V4 API：本文：`{"data": {"name": "New Folder Name"}}`。
DELETE	`/v2/assets/{asset_id}` （アセットを削除）	DELETE	`/v4/accounts/{account_id}/folders/{folder_id}` （フォルダーを削除）	フォルダーを削除します。

5.ファイル

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
POST	`/v2/assets/{parent_asset_id}/children` （アセットを作成）	POST	`/v4/accounts/{account_id}/folders/{folder_id}/files` （ファイルを作成）	レガシー API：name、type、filetype、fileSize、&auto_version_id が必要となります。 V4 API：パスパラメーターで account_id と folder_id が必要であり、ペイロードで file_size と media_type_name が必要となります
GET	`/v2/assets/{asset_id}` （アセットを取得）	GET	`/v4/accounts/{account_id}/files/{file_id}` （ファイルを表示）	V4 API：Frame.io からのアセットのダウンロードを有効にするには、`api-version:experimental` が `media_links` を返す必要があります
PUT	`/v2/assets/{asset_id}` （アセットを更新）	PATCH	`/v4/accounts/{account_id}/files/{file_id}` （ファイルを更新）	V4 では api-version:experimental が必要です
DELETE	`/v2/assets/{asset_id}` （アセットを削除）	DELETE	`/v4/accounts/{account_id}/files/{file_id}` （ファイルを削除）	204 成功したコンテンツがありません。
POST	`/v2/assets/{asset_id}/version` （アセットのバージョン管理）	POST	`/v4/accounts/{account_id}/folders/{folder_id}/version_stacks` （バージョンスタックを作成）	V4 では api-version:experimental が必要です

6.コメント

コメントエンドポイントの初期サポートがリリースされました。近日中にリリースされる予定の追加機能がいくつかあります。近日リリース予定の機能のサポートには、以下が含まれます。

近日リリース予定の機能：

範囲ベースのコメント
コメントへの返信を残す
コメントの添付ファイル
コメントのリアクション（絵文字など）
コメント完了ステータスの表示または変更
ハイパーリンクまたは@メンション（コメントエンティティ）
コメントを閲覧したユーザーの表示（インプレッション）

「タイムスタンプ」フィールドは、タイムスタンプではなく、コメントが残されたフレームスタンプ（1 から始まる）を表します

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
GET	`/v2/assets/{asset_id}/comments` （コメントスレッドからすべてのコメントと返信を取得）	GET	`/v4/accounts/{account_id}/files/{file_id}/comments` （コメントを一覧表示）	ファイルのコメントを一覧表示します。
POST	`/v2/assets/{asset_id}/comments` （コメントを作成）	POST	`/v4/accounts/{account_id}/files/{asset_id}/comments` （コメントを作成）	コメントを作成します。本文が類似しています。`{"text":"Nice","timestamp":12.3}`。
GET	`/v2/comments/{comment_id}` （ID 別にコメントを取得）	GET	`/v4/accounts/{account_id}/comments/{comment_id}` （コメントを表示）	ID 別に単一のコメントを取得します。
PUT	`/v2/comments/{comment_id}` （コメントを更新）	PATCH	`/v4/accounts/{account_id}/comments/{comment_id}` （コメントを更新）	テキスト、時刻などを更新します
DELETE	`/v2/comments/{comment_id}` （コメントを削除）	DELETE	`/v4/accounts/{account_id}/comments/{comment_id}` （コメントを削除）	コメントを削除します。

7.共有（レビューリンク / プレゼンテーション）

Frame V4 では、共有リンクがレビューリンクとプレゼンテーションリンクの間で分割されなくなりました。V4 では、レビューまたはプレゼンテーションエクスペリエンスに合わせて、同じリンクを異なるスタイルで設定できるようになりました。

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
GET	`/v2/projects/{project_id}/review_links` （プロジェクト内のレビューリンクを一覧表示）	GET	`/v4/accounts/{account_id}/projects/{project_id}/shares` （共有を一覧表示）	プロジェクト内の共有を一覧表示します
POST	`/v2/projects/{project_id}/review_links` （レビューリンクを作成）	POST	`/v4/accounts/{account_id}/projects/{project_id}/shares` （共有を作成）	新しい共有リンクを作成します。本文は `{"data":{"name":"Review Link","type":"review"}}` となる場合があります。
POST	`/v2/review_links/{link_id}/assets` （アセットをレビューリンクに追加）	POST	`/v4/accounts/{account_id}/shares/{share_id}/assets` （共有する新しいアセットを追加）	これにより、ファイル、フォルダー、バージョンスタックなどがサポートされるかどうかは未定です。API リファレンスを更新して、以下を明確にする必要があります
DELETE	存在しません	DELETE	`/v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id}` （共有を削除）	共有からアセットを削除します
DELETE	`/v2/review_links/{link_id}` （レビューリンクを削除）	DELETE	`/v4/accounts/{account_id}/shares/{share_id}` （共有を削除）	共有リンクを削除します。
PUT	`/v2/review_links/{review_link_id}` （レビューリンクを更新）	PATCH	`/v4/accounts/{account_id}/shares/{share_id}` （共有を更新）	共有リンクの更新

8.Webhook

Frame.io V4 のリソースに多くの変更が加えられたことと、V4 の Webhook の試験的な状態を考えると、Webhook をトリガーするサポートされている「イベント」の数は大きく異なります。

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
POST	`/v2/teams/{team_id}/hooks` （Webhook を作成）	POST	`/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks` （Webhook を作成）	`{"data":{"url":"...","events":["file.created",...]}}` を表示します。
該当なし	該当なし	GET	`/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks` （一覧を取得）	ワークスペースのすべての Webhook を取得します
GET	`/v2/hooks/{hook_id}` （Webhook を取得）	GET	`/v4/accounts/{account_id}/webhooks/{webhook_id}` （Webhook を取得）	Webhook 情報を取得します
PUT	`/v2/hooks/{hook_id}` （Webhook を更新）	PATCH	`/v4/accounts/{account_id}webhooks/{webhook_id}` （Webhook を更新）	Webhook 設定を更新します
DELETE	`/v2/hooks/{hook_id}` （Webhook を削除）	DELETE	`/v4/accounts/{account_id}/webhooks{webhook_id}` （Webhook を削除）	Webhook を削除します。

9.カスタムアクション

レガシーメソッド	レガシーエンドポイント	V4 メソッド	V4 エンドポイント	注意
POST	`/v2/teams/{team_id}/actions`（カスタムアクションを作成）	POST	`/v4/accounts/{account_id}/workspaces/{workspace_id}/actions`（カスタムアクションを作成）	ワークスペースにカスタムアクションを作成します。
DELETE	`/v2/actions/{action_id}`（カスタムアクションを削除）	DELETE	`/v4/accounts/{account_id}/actions/{action_id}`（カスタムアクションを削除）	カスタムアクションを削除します。
PUT	`v2/actions/{action_id}`（カスタムアクションを更新）	PATCH	`/v4/accounts/{account_id}/actions/{action_id}`（カスタムアクションを更新）	カスタムアクションの詳細を更新します。
GET	`/v2/teams/{team_id}/actions`（チームのカスタムアクションを取得）	GET	`/v4/accounts/{account_id}/workspaces/{workspace_id}/actions` を取得（カスタムアクションを一覧表示）	特定のワークスペースのカスタムアクションを一覧表示します。
GET	`/v2/actions/{action_id}`（ID 別にカスタムアクションを取得）	GET	`/v4/accounts/{account_id}/actions/{action_id}`（カスタムアクションの詳細を表示）	カスタムアクションの詳細を表示します。

移行手順

サポートされていないエンドポイントの削除

サポートされていないレガシーエンドポイントをすべて削除します。

アドビプロジェクトの作成

Adobe Developer Console の新規プロジェクトを作成で、ユーザー認証タイプを選択し、アプリで OAuth サポートを実装します。

ベース URL の更新

ベース URL を更新が api.frame.io/v2/... から api.frame.io/v4/... に変更になりました。

API 要求の更新

コード内でAPI 要求を更新して、新しいエンドポイントスキーマを参照します。

JSON ペイロードの更新

要求 / 応答スキーマのJSON ペイロードを更新して、正しいフィールドを作成および使用していることを確認します。

用語の更新

次の用語が更新されました。「チーム」 → 「ワークスペース」、「アセット」 → 「ファイル / フォルダー」、「レビューリンク」または「プレゼンテーションリンク」 → コード内およびフロントエンド内の「共有」。

エンドポイントのテスト

新しく更新されたすべてのエンドポイントをテストします。403、404、422 が表示されている場合は、エンドポイント、リクエストペイロードシェイプなどを確認します。

エラーレスポンスの解析

API 呼び出しが失敗した場合は、新しい詳細なエラーレスポンスを解析し、{"errors": [...]} JSON レスポンスで問題を探します。

テストユーザーの追加

Adobe Developer Console からプロジェクトにテストユーザーを追加します。

本番環境へのデプロイ

V4 Frame.io アカウントで検証後、本番環境にデプロイします。

エラー処理と一般的な問題

クライアントエラー（4xx）

400 Bad Request：ペイロードの精度を確認してください。
401 Unauthorized：OAuth トークンを更新または再認証してください。
403 Forbidden：スコープがないか、ユーザーにアクセス権がありません。
404 Not Found：エンドポイント、API バージョン、または ID を確認してください。
422 Unprocessable Entity：Validate request data
429 Rate limited：バックオフによる再試行を実装してください。

サーバーエラー（5xx）

500 server error：しばらくしてから再試行してください。

レガシー API エンドポイントは、V4 API では現在使用できません。

次のレガシー API エンドポイントは、V4 API では現在使用できません。

1.アカウントとユーザー情報

GET /v2/accounts/{account_id}
GET /v2/projects/shared
GET /v2/accounts/{account_id}/membership

2.ファイルとフォルダー

DELETE /v2/assets/{asset_id}/unversion

3.チーム / ワークスペース

GET /v2/teams/{team_id}/membership

4.コメント

GET /v2/comments/{comment_id}/impressions

5.Webhook

GET /v2/accounts/{account_id}/webhooks