> 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 실험적: 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는 웹 애플리케이션의 기능과 동일하게, 전체 계정 내 에셋에 대한 심층적이고 다각적인 검색을 지원합니다. 가장 유용하게 사용되는 필터는 Team, Project, Status이지만, 필터와 정렬 기능을 다양하게 조합하여 API 기반의 매우 구체적인 데이터 세트를 생성할 수 있습니다. 일반적으로 `account_id`, `q`(쿼리), `sort`를 제외한 모든 필터는 동일한 구조를 따르며, 아래에 모두 설명되어 있습니다. search-filters.png 2022년 3월 현재, 검색 API의 페이징 기능에 영향을 미치는 알려진 버그가 있습니다. 이 버그가 해결될 때까지 검색 API를 사용하여 여러 페이지의 결과(즉, 100개 이상의 에셋)를 반복적으로 조회하는 것은 권장하지 않습니다. 요청한 페이지 크기와 실제 반환된 에셋 수가 일치하지 않을 수 있기 때문입니다. ## 기본값 검색을 트리거하는 API 요청은 항상 동일합니다. 항상 동일한 요청입니다. `POST` to `https://api.frame.io/v2/search/library` 명시적으로 제공되지 않은 경우, 검색 조정을 위한 기본값은 다음과 같습니다. | 특성 | 기본값 | 설명 | |:--------|:------------|:----------| | `page_size` | 10 | 페이지당 10개의 에셋이 반환됩니다. | | `page` | 1 | 쿼리는 응답의 첫 페이지를 반환합니다. | | `sort` | `relevance` | "관련성"은 특별히 조정된 속성 세트를 기반으로 에셋을 정렬하려고 시도합니다. 쿼리가 없는 경우, 관련성은 업로드 최신성에 크게 치우칩니다. | ## 이 가이드에 대하여 이 가이드에서는 다음 조건과 일치하는 검색 쿼리를 작성하는 과정을 안내합니다. * 계정 내에 있는 에셋 * `"moon"` 쿼리와 일치 * 특정 프로젝트에 존재함 * 2020년 4월 1일에서 30일 사이에 업로드됨 * "승인됨"로 표시됨 검색을 위한 본문은 최종적으로 다음과 같은 형태가 됩니다. ```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(`account_id`), query (`q`), `sort`은 검색 쿼리의 `filter` 속성 외부에 존재하는 가장 기본적인 세 가지 구성 요소입니다. #### 계정 컨텍스트 기술적으로 검색을 수행하는 데 필요한 유일한 속성은 `account_id`입니다. 이것만으로도 기본 페이지 매김 값(1페이지부터 시작하여 페이지당 10개의 에셋)을 적용해 계정 내의 모든 에셋(폴더 포함)을 가져올 수 있습니다. ```json { "account_id": "" } ``` #### 검색 쿼리 그 다음으로 가장 일반적으로 포함되는(그리고 유용한) 속성은 쿼리 자체입니다. 참고: Frame.io API 검색은 null 쿼리를 허용하므로 와일드카드(`*`) 쿼리가 필요하지 않습니다. 무언가를 검색하거나 계정 내 모든 에셋의 정렬된 목록(필터링될 수도 있음)을 요청하는 것입니다. 이 가이드의 예시에서는 "moon"이라는 용어를 검색합니다. ```json { "account_id": "", "q": "moon" } ``` ### 정렬 sort.png Frame.io는 여러 가지 정렬 옵션을 지원합니다. 정렬 순서 구문은 모든 옵션에서 유사합니다. * 기본 정렬 방향이 존재합니다. * 정렬 기준을 반대로 바꾸려면 정렬 값 앞에 음수 기호(`-`)를 추가합니다. 예를 들어 역알파벳순(Z부터 A)으로 정렬하려면 `"sort": "-name"`으로 선언합니다. 기본 정렬 방식은 "관련성"입니다. 따라서 별도로 선언할 필요가 없으며, `sort` 속성이 제공되지 않은 경우 이 방식이 적용된 것으로 간주됩니다. | 정렬 옵션 | 특성 | 기본 방향 | |:----------|:--------|:----------------| | **관련성** | N/A | N/A | | **업로드한 일자** | `inserted_at` | 오래된 항목 순 | | **이름** | `name` | A~Z | | **크기** | `filesize` | 가장 작은 용량부터 | | **업로더** | `creator.name` | A~Z | 이제 쿼리를 구성해 나가면서, 이름(`name`)을 A부터 Z까지 정렬(`sort`)하는 조건을 추가할 수 있습니다. ```json { "account_id": "", "q": "moon", "sort": "name" } ``` ### 필터 및 페이지 매김 필터는 Frame.io 에셋 검색에서 가장 다루기 까다로우면서도 가장 강력한 기능입니다. 필터는 단일 `filter` 오브젝트 내에 작성되며, 모두 작업(`op`)과 값(`value`)이라는 동일한 패턴을 따릅니다. 필터는 다음과 같은 일반적인 약어를 사용하며, "equals" 이외의 비교 옵션은 날짜 및 크기 쿼리에만 사용할 수 있습니다. * `eq` -- 같음 * `lt` -- 보다 작음 * `gt` -- 보다 큼 * `lte` -- 작거나 같음 * `gte` -- 크거나 같음 * `match` -- 정확히 일치, 업로더 및 파일 유형 필터에만 사용 예를 들어 이미 알고 있는 `project_id`와 일치시키는 `filter`는 다음과 같이 구성됩니다. ```json { "filter": { "project_id": { "op": "eq", "value": "" } } } ``` ### 옵션 및 작업 다음 표는 각 필터 유형과 관련된 옵션 및 작업을 설명합니다. | 필터 옵션 | 특성 | 지원되는 작업 | 지원되는 값 | |:------------|:--------|:-------------------|:---------------| | **Archived** | `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` | `audio`, `document`, `folder`, `image`, `other`, `stream`, `video` | | **업로더** | `creator.name` | `match` | `<name>` | 해당 사용자가 더 이상 사용자 검색 인덱스에 존재하지 않으므로 계정 멤버가 아닌 생성자를 검색하는 것은 작동하지 않습니다. 계속해서 쿼리를 구축하기 위해 이제 다음 조건의 에셋에 대한 필터를 추가할 수 있습니다. * 특정 프로젝트에 존재함 * 2020년 4월 1일에서 30일 사이에 업로드됨 * "승인됨"으로 표시됨 ```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)에서 별도의 가이드를 참조하세요.