> 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 は、アカウント全体のアセットの詳細なファセット検索をサポートしており、web アプリケーションの機能をミラーリングします。最も一般的で便利なフィルターはチーム、プロジェクト、およびステータスですが、フィルターと並べ替えを独自の方法で組み合わせて、非常に具体的な API 主導型セットを生成できます。一般に、`account_id`、`q`（クエリ）、および `sort` を除くすべてのフィルターは、同じ構造に従い、以下で説明されています。

![search-filters.png](/_fern-img/d468e3a3b48184af611e5af020bee1474a328ab3fc5090df704dfd6c9b603ba7.webp)

<Warning title="リクエストされたページサイズと返されたページサイズが一致しない">
2022年3月現在、検索 API のページング機能に影響を与える既知のバグがあります。このバグが解決されるまで、検索 API を使用して結果の複数ページ（例：100 を超えるアセット）を反復処理することはお勧めしません。リクエストされたページサイズが実際に返されたアセット数に対応していない可能性があるからです。
</Warning>

## デフォルト

検索をトリガーする API リクエストは、常に同じです。

常に同じリクエストです

`https://api.frame.io/v2/search/library` への `POST`

明示的に指定しなかった場合、検索チューニングのデフォルト値は、次のとおりです。

| 属性| デフォルト値| 説明|
|:----------|:----------|:----------|
| `page_size`| 10| 1 ページあたり 10 個のアセットが返されます。|
| `page`| 1| このクエリは、応答の最初のページを返します。|
| `sort`| `relevance`| 「relevance」は、特別にチューニングされた属性セットに基づいてアセットを並べ替えようとします。クエリがない場合、relevance は、アップロードの最新性に向けて大きく偏っています。|

## このガイドについて
このガイドでは、次の条件に一致する検索クエリを構築するプロセスについて説明します。

- アカウント内のアセット
- クエリ `"moon"` と一致
- 特定のプロジェクトにある
- 2020 年 4 月 1 日から 30 日までの間にアップロードされた
- かつ、「承認済み」になった

検索の本文は、次のようになります。

```json
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name",
    "filter": {
        "inserted_at": [
            {
                "op": "gte",
                "value": "2020-04-01T04:00:00.000Z"
            },
            {
                "op": "lte",
                "value": "2020-04-30T03:59:59.999Z"
            }
        ],
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        },
        "label": {
            "op": "eq",
            "value": "approved"
        }
    },
    "page_size": 10,
    "page": 1
}
```

### アカウント、クエリおよび並べ替え
アカウント（`account_id`）、クエリ（`q`）、および `sort` は 、検索クエリの `filter` 属性の外側に存在する最も基本的な 3 つの構成要素です。

#### アカウントコンテキスト
技術的には、検索を実行するのに必要な唯一の属性は `account_id` です。これにより、アカウント上のすべてのアセット（フォルダーを含む）が、デフォルトのページネーション値（1 ページから、ページあたり 10 アセット）で取り込まれます。

```json
{
    "account_id": "<account_id>"
}
```

#### 検索クエリ

次に最も一般的な含めるべき属性は、クエリ自体です。メモ：Frame.io の API 検索は null クエリを受け入れるので、ワイルドカード（`*`）クエリは必要ありません。何かを検索するか、アカウント内のすべてのアセット（フィルタリングされている可能性がある）の種類をリクエストします。

ここでは、用語「moon」を検索します。

```json
{
    "account_id": "<account_id>",
    "q": "moon"
}
```

### 並べ替え

![sort.png](/_fern-img/bd057586bfc5499df0b46d41ae74d90e53beb6500bb87f639a730545ccb3f1c8.webp)

Frame.io は、様々な並べ替えオプションをサポートしています。並べ替え順序の構文は、オプションにわたって同様です。

- デフォルトの並べ替え方向があります
- その方向を逆にするには、並べ替え値に、マイナス `-` の接頭辞を付けます

例えば、アルファベットの逆の順序（Z から A）で並べ替えるには、`"sort": "-name"` を宣言します。

デフォルトの並べ替え操作は「関連性」です。したがって、これは宣言する必要はなく、`sort` 属性が指定されていない場合、宣言されたと見なされます。

| 並べ替えオプション| 属性| デフォルトの方向|
|:----------|:----------|:----------|
| **関連性**| 該当なし| 該当なし|
| **アップロード日**| `inserted_at`| 古い順|
| **名前**| `name`| A から Z|
| **サイズ**| `filesize`| 小さい順|
| **アップロード者**| `creator.name`| A から Z|

したがって、クエリを構築するときは、`name` に `sort` で A から Z を追加できるようになりました。

```json
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name"
}
```

### フィルターとページネーション

フィルターは、Frame.io のアセット検索で最も難しく、最も強力な機能です。フィルターは、1 個の `filter` オブジェクト内に書き込まれ、すべて同じパターンの演算（`op`）および `value` に従います。フィルターでは、次の一般的な略語が使用され、「等しい」以外の等価オプションは日付およびサイズクエリ用に予約されています。

- `eq` --等しい
- `lt` --より小さい
- `gt` --より大きい
- `lte` --より小さいか等しい
- `gte` --以上
- `match` --完全一致。アップロード者フィルターおよび Filetype フィルターにのみ使用されます

例えば、既知の `project_id` で一致する `filter` は、次のように構成します。

```json
{
    "filter": {
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        }
    }
}
```

### オプションと演算

次の表では、各フィルタータイプに関連するオプションおよび演算について説明します。

| フィルターオプション| 属性| サポートされている演算| サポートされている値|
|:----------|:----------|:----------|:----------|
| **アーカイブ済み**| `archived`| `eq`| `true`、`false`|
| **アップロード日**| `inserted_at`| `eq`、`lt`、`gt`、`lte`、`gte`| `<datetime>`（ISO-8601、UTC）|
| **削除済み**| `deleted`| `eq`| `true`、`false`|
| **ファイルタイプ**| `filetype`| `match`| `<MIME type>`|
| **プライベート**| `private`| `eq`| `true`、`false`|
| **プロジェクト**| `project_id`| `eq`| `<project_id>`|
| **サイズ**| `filesize`| `eq`、`lt`、`gt`、`lte`、`gte`| `size`（バイト数）|
| **ステータス**| `label`| `eq`| `none`、`in_progress`、`needs_review`、`approved`|
| **チーム**| `team_id`| `eq`| `<team_id>`|
| **タイプ**| `asset_type`| `eq`| `audio`、`document`、`folder`、`image`、`other`、`stream`、`video`|
| **アップロード者**| `creator.name`| `match`| `<name>`|

<Warning title="インデックスを入力するには、アップロード者がアクティブなアカウントメンバーである必要があります">
アカウントのメンバーではなくなったクリエイターの検索は機能しません。そのユーザーがユーザー検索インデックスに存在しないからです。
</Warning>

クエリの構築を続行するために、次のようなアセットのフィルターを追加できるようになりました。

- 特定のプロジェクトにある
- 2020 年 4 月 1 日から 30 日までの間にアップロード済み
- 「承認済み」としてマーク済み

```json
{
    "account_id": "<account_id>",
    "q": "moon",
    "sort": "name",
    "filter": {
        "inserted_at": [
            {
                "op": "gte",
                "value": "2020-04-01T04:00:00.000Z"
            },
            {
                "op": "lte",
                "value": "2020-04-28T03:59:59.999Z"
            }
        ],
        "project_id": {
            "op": "eq",
            "value": "<project_id>"
        },
        "label": {
            "op": "eq",
            "value": "approved"
        }
    }
}
```

<Note title="ページネーション">
検索エンドポイントは、リクエスト本文の最も外側のレイヤーにある `page_size` 属性と `page` 属性を使用して、他のエンドポイントとまったく同じようにページネーションされます。ページネーションの詳細については、[こちら](https://developer.frame.io/docs/getting-started/key-concepts#pagination)の別ガイドを参照してください。
</Note>