> This page is for プラットフォーム, version レガシー.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 Experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - レガシー: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# 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 と認証

| **V3**| **V4**|
|----------|----------|
| `Authorization: Bearer <token>` での開発者トークン（ベアラー `<token>`）または Frame.io OAuth 2.0| Adobe IMS OAuth 2.0（Adobe Developer Console にプロジェクトを作成する必要があります）、次を使用：`Authorization: Bearer <adobe_access_token>`|

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

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

#### フォルダーの作成

- **V3（フォルダーの作成）：**
  ```http
  POST /v2/assets/{parent_asset_id}/children
  Content-Type: application/json

  {
    "name": "My New Folder",
    "type": "folder"
  }
  ```