> 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 > - Версия 4 экспериментальная: 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. # Поиск ресурсов # Обзор API-интерфейс Frame.io поддерживает глубокий фасетный поиск ресурсов по всей учетной записи, дублируя функциональность в веб-приложении. Хотя наиболее полезные фильтры — это команда, проект и статус, фильтры и сортировку можно комбинировать уникальными способами для создания очень конкретных наборов, управляемых API-интерфейсами. В целом все фильтры, кроме `account_id`, `q` (запрос) и `sort`, имеют одинаковую структуру и все объясняются ниже. search-filters.png По состоянию на март 2022 года известна ошибка, влияющая на функцию постраничного вывода API-интерфейса поиска. Пока эта ошибка не устранена, мы не рекомендуем использовать поисковой API-интерфейс для перебора нескольких страниц результатов (т. е. более 100 ресурсов), поскольку запрошенный размер страницы может не соответствовать фактическому количеству возвращенных ресурсов. ## Значения по умолчанию Запрос API-интерфейса для запуска поиска всегда одинаковый: это всегда один и тот же запрос `POST` по адресу `https://api.frame.io/v2/search/library` Если не указано явно, значения по умолчанию для настройки поиска следующие: | Атрибут | Значение по умолчанию | Описание | |:--------|:------------|:----------| | `page_size` | 10 | На странице будет возвращаться 10 ресурсов. | | `page` | 1 | Запрос вернет первую страницу ответа. | | `sort` | `relevance` | «Relevance» пытается упорядочить ресурсы на основе специально настроенного набора атрибутов. При отсутствии запроса релевантность сильно смещена в сторону недавних операций добавления. | ## Об этом руководстве В этом руководстве представлен процесс создания поискового запроса, который соответствует следующим критериям: * ресурсы в учетной записи; * соответствует запросу `"moon"`; * находится в конкретном проекте; * добавление с 1 по 30 апреля 2020 года; * наличие статуса «Утверждено». Основная часть нашего поиска будет выглядеть следующим образом: ```json { "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": "" }, "label": { "op": "eq", "value": "approved" } }, "page_size": 10, "page": 1 } ``` ### Учетная запись, запрос и сортировка. Учетная запись (`account_id`), запрос (`q`) и `sort` — это три основных элемента, которые находятся вне атрибутов `filter` в поисковом запросе. #### Контекст учетной записи Технически единственный атрибут, необходимый для выполнения поиска, — `account_id`. Это приведет к выгрузке всех ресурсов (включая папки) в учетной записи с использованием параметров разбивки на страницы по умолчанию (10 ресурсов на страницу, начиная со страницы 1). ```json { "account_id": "" } ``` #### Поисковый запрос Следующим наиболее распространенным (и полезным) атрибутом является сам запрос. Примечание. Поскольку поисковой API-интерфейс Frame.io принимает нулевой запрос, подстановочный знак (`*`) не требуется. Вы либо ищете что-то конкретное, либо запрашиваете (возможно, отфильтрованную) сортировку всех ресурсов в учетной записи. В нашем случае мы будем искать слово «луна». ```json { "account_id": "", "q": "moon" } ``` ### Сортировка sort.png Frame.io поддерживает множество различных параметров сортировки. Синтаксис порядка сортировки одинаков для всех параметров: * Есть направление сортировки по умолчанию. * Чтобы изменить это направление на противоположное, добавьте перед значением сортировки знак минус `-`. Например, для сортировки в обратном алфавитном порядке (от Я до А) нужно сообщить `"sort": "-name"`. Операция сортировки по умолчанию — «Relevance». Соответственно, ее не нужно сообщать, и она будет применена, если атрибут `sort` не указан. | Параметр сортировки | Атрибут | Направление по умолчанию | |:----------|:--------|:----------------| | **Релевантность** | н/д | н/д | | **Дата добавления** | `inserted_at` | Сначала старые | | **Имя** | `name` | от А до Я | | **Размер** | `filesize` | От меньшего к большему | | **Добавляющий пользователь** | `creator.name` | от А до Я | Соответственно, по мере создания запроса мы теперь можем добавить `сортировку` по `имени` от А до Я: ```json { "account_id": "", "q": "moon", "sort": "name" } ``` ### Фильтры и разбивка на страницы Фильтры — это самая сложная и в то же время самая эффективная функция поиска ресурсов Frame.io. Фильтры записываются в одном объекте `filter` и следуют одной схеме с операцией (`op`) и `значением`. Фильтры будут использовать следующие общие сокращения, при этом варианты эквивалентности, отличные от «equals», зарезервированы для запросов даты и размера: * `eq` — равно * `lt` — менее чем * `gt` — более чем * `lte` — менее чем или равно * `gte` — более чем или равно * `match` — точное соответствие, используемое только для фильтров «Добавляющий пользователь» и «Тип файла» Например, `фильтр` для сопоставления с известным `project_id` будет создан следующим образом: ```json { "filter": { "project_id": { "op": "eq", "value": "" } } } ``` ### Параметры и операции В следующей таблице описаны параметры и операции, связанные с каждым типом фильтра. | Параметр фильтра | Атрибут | Поддерживаемые операции | Поддерживаемые значения | |:------------|:--------|:-------------------|:---------------| | **Архивировано** | `archived` | `eq` | `true`, `false` | | **Дата добавления** | `inserted_at` | `eq`, `lt`, `gt`, `lte`, `gte` | `<datetime>` (ISO-8601, UTC) | | **Удалено** | `deleted` | `eq` | `true`, `false` | | **Тип файла** | `filetype` | `match` | `` | | **Частный** | `private` | `eq` | `true`, `false` | | **Проект** | `project_id` | `eq` | `<project_id>` | | **Размер** | `filesize` | `eq`, `lt`, `gt`, `lte`, `gte` | `размер` (в байтах) | | **Статус** | `label` | `eq` | `none`, `in_progress`, `needs_review`, `approved` | | **Команда** | `team_id` | `eq` | `<team_id>` | | **Тип** | `asset_type` | `eq` | `аудио`, `документ`, `папка`, `изображение`, `другое`, `поток`, `видео` | | **Добавляющий пользователь** | `creator.name` | `match` | `<name>` | Поиск создателей, которые больше не являются участниками учетной записи, работать не будет, поскольку этот пользователь больше не находится в индексе поиска пользователей. Чтобы продолжить создание запроса, теперь можно добавить фильтр для ресурсов, которые: * находится в конкретном проекте; * добавлены с 1 по 30 апреля 2020 года; * помечены как «Утверждено». ```json { "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": "" }, "label": { "op": "eq", "value": "approved" } } } ``` Конечная точка поиска разбивает на страницы точно так же, как и любая другая конечная точка, через атрибуты `page_size` и `page`, которые находятся на внешнем слое тела запроса. Подробнее о разбивке на страницы см. в отдельном руководстве [здесь](/platform/v2/key-concepts#pagination).