Frame.io API V3 → V4 移行ガイド

次のガイドは、Frame.io API V3（ドキュメントでは、「レガシー」や「v2」エンドポイントと呼ばれる場合があります）から Adobe Frame.io API V4 に移行するのに役立ちます。これは、Dropbox API 移行例と同じスタイルおよび構造であり、エンドポイントマッピング、ペイロード変更、認証更新などを包括的に紹介します。

---

開発者向けの移行チェックリスト

1. 現在の V3 使用状況の識別：

   • アプリが行うすべての呼び出し（ファイルの作成、フォルダーのリスト、コメントの追加など）をリストします。
   • それぞれをマッピングテーブルと照合して、同等の新しい V4 を見つけます。

2. Adobe IMS 資格情報の取得（OAuth 2.0）：

   • Adobe Developer Console に、統合を作成します。
   • OAuth 2.0 クライアント資格情報およびスコープ（Frame.io アクセス）を設定します。
   • 古い Frame.io 開発者トークンを新しい IMS トークンフローに置換します。

3. エンドポイント URL の更新：

   • V3：https://api.frame.io/v2/...（assets/{asset_id} を使用して操作されたアセットで）。
   • V4：https://api.frame.io/v4/ とエンドポイントには、accounts/{account_id} と folders/{folder_id}／files/{file_id} が含まれます。

4. リクエストペイロードおよび応答解析の調整：

   • V4 は通常、data オブジェクト（{"data": {...}} など）のデータをラッピングします。
   • フォルダー作成、ファイルアップロードなどでは、新しい JSON フィールド名（file_size、media_type など）を使用します。
   • チーム → ワークスペース変更：team_id（V3）を workspace_id（V4）に置換します。

5. Webhook 登録の作り直し：

   • （V4 で発生しなくなった）古い V3 Webhook を削除するか、無効にします。
   • POST /v4/accounts/{account_id}/webhooks の下で、新しい Webhook を登録します。

6. エラー処理およびレート制限のテスト：

   • コードが新しい 4xx/5xx 応答およびリクエスト／応答形式の変更を処理することを確認します。
   • V4 は、異なるエラー構造（例えば、より構造化された JSON、競合の 409 など）を返す場合があります。

7. アクセスおよび権限の確認：

   • Adobe IMS トークンが正しいアカウント／ワークスペース権限を持つユーザー（またはサービスアカウント）に属していることを確認します。
   • 「チームレベル」スコープを持つレガシー V3 トークンは、V4 では有効ではありません。

8. 展開および監視：

   • 最初に、サンドボックスまたは開発環境で更新されたコードをテストします。
   • 4xx/5xx または予期しない動作がないかログを監視し、完全に展開する前に問題を修正します。

---

エンドポイント：V3 → V4 マッピング

以下は、重要な Frame.io V3 エンドポイント（左）と同等の V4 エンドポイント（右）を並べて比較したものです。このセクションは、Dropbox の「v1 → v2 マッピング」テーブルに基づいています。

**ヒント：**このテーブルでは、一般的なファイル、フォルダー、およびプロジェクト操作について説明します。特殊なエンドポイント（Camera to Cloud など）は省略されています。

OAuth と認証

**注意：**従来の開発者トークンは自動的には変換できません。新しい IMS OAuth フローを実装する必要があります。
ドキュメント：Adobe Frame.io アクセストークンを取得する方法

フォルダーおよびファイル操作

フォルダーの作成

• V3（フォルダーの作成）：

  1
  POST /v2/assets/{parent_asset_id}/children
  2
  Content-Type: application/json
  3
  4
  {
  5
    "name": "My New Folder",
  6
    "type": "folder"
  7
  }