# 필터링, 필드 및 확장

> Content Delivery API 읽기 시 필터링, 정렬, 필드 투영, 참조 확장 및 미디어 해결을 수행하여 페이지당 한 번의 요청으로 데이터를 효율적으로 가져옵니다.

> Markdown version of https://kanorio.com/ko/developers/basics/fields-and-expand. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/fields-and-expand.md

Content Delivery API를 통한 컬렉션 읽기에는 간단한 쿼리 언어가 사용됩니다. 이는 사용자의 고유 컬렉션뿐만 아니라 `blog`, `blog_categories`, `blog_tags`, `authors` 와 같은 기본 제공 컬렉션에서도 동일하게 작동합니다.

```bash
curl "https://{site}/api/v1/collections/courses/items?filter[level]=beginner&sort=-publishedAt&fields=title,cover,teacher&expand=teacher&limit=12"
```

## 필터

조건에는 대괄호 표기법을 사용합니다: `filter[field][operator]=value`。`filter[field]=value` 는 `eq` 의 약어입니다. 조건은 AND로 결합됩니다. OR을 사용하려면 `filter[any][0]`, `filter[any][1]` 와 같이 조건을 그룹화하십시오.

| 연산자 | 대상 | 예시 |
|---|---|---|
| `eq`, `ne` | 스칼라 | `filter[level][eq]=beginner` |
| `in`, `nin` | 스칼라, 쉼표로 구분된 값 | `filter[level][in]=beginner,advanced` |
| `gt`, `gte`, `lt`, `lte` | 숫자, 날짜 | `filter[price][lte]=50` |
| `contains`, `ncontains` | 텍스트 | `filter[title][contains]=bread` |
| `match` | 텍스트 및 리치 텍스트, 여러 단어 | `filter[content][match]=sourdough starter` |
| `exists` | 모든 필드 | `filter[cover][exists]=true` |
| `has` | 멀티 셀렉트, 멀티 레퍼런스 | `filter[tags][has]=tag_01` |
| `eq_slug` | 레퍼런스 (참조 항목의 슬러그 기준) | `filter[teacher][eq_slug]=ada` |
| `has_slug` | 멀티 레퍼런스 (슬러그 기준) | `filter[categories][has_slug]=recipes` |

`slug`, `publishedAt`, `createdAt`, `updatedAt` 은 모든 컬렉션에서 필터링할 수 있습니다. 날짜에는 `now-30d` 또는 `now+1w` 와 같은 상대 값을 사용할 수 있습니다. 조건 및 값에 대한 정확한 제한 사항은 레퍼런스를 참조하십시오.

## 정렬

`sort=-publishedAt,title` 은 최대 몇 개의 필드를 기준으로 정렬합니다. 앞의 `-` 는 내림차순을 의미합니다. 스칼라 필드 및 위의 항목 속성은 정렬할 수 있습니다. 리치 텍스트, JSON, 미디어 및 다중 값 필드는 정렬할 수 없습니다.

## 필드

`fields=title,excerpt,cover` 는 `fieldData` 의 지정된 키만 반환합니다. `id`, `slug`, `publishedAt`, `updatedAt` 은 항상 반환됩니다. 모든 기사 본문을 다운로드하지 않도록 목록 페이지에서 사용하십시오.

## 확장

`expand=teacher` 는 1단계 참조 조회를 대체합니다. 각 항목은 참조된 항목이 포함된 `expanded.teacher` 를 가져오며, 해당 이미지는 최상위 `assets` 맵에 결합됩니다. `blog` 에서 `expand=authors,categories,tags` 를 사용하면 게시물의 작성자, 카테고리, 태그가 확장되며, `primary_author` 및 `primary_category` 를 통해 각각의 첫 번째 항목을 가져올 수 있습니다.

## 에셋

이미지, 갤러리 및 파일 필드는 에셋 ID를 보유합니다. 미디어를 참조하는 모든 응답에는 이를 해결하기 위한 최상위 `assets` 맵이 포함되어 있으므로 두 번째 요청이 필요하지 않습니다.

```json
{
  "assets": {
    "ast_01": {
      "assetId": "ast_01",
      "url": "https://imagedelivery.net/.../public",
      "width": 1600,
      "height": 1067,
      "alt": "Loaves cooling on a rack",
      "focus": { "x": 0.5, "y": 0.4 },
      "placeholder": "data:image/webp;base64,...",
      "edgeColor": "#f4efe6",
      "mimeType": "image/jpeg",
      "kind": "image"
    }
  }
}
```

- `placeholder` 는 흐릿한 작은 미리보기 이미지로, `<img>` 태그의 블러 처리나 Next.js의 `blurDataURL` 에 적합합니다.
- `focus` 는 0에서 1 사이의 좌표로 나타내는 초점입니다. 자르기 시 `object-position` 으로 사용하십시오. 설정되지 않은 경우 `null` 입니다.
- `edgeColor` 는 제품 사진 배경의 흰색과 같이 4개의 가장자리 모두에서 공유되는 단색입니다. `object-fit: contain` 으로 이미지를 표시할 때 배경으로 사용하십시오. 투명하거나 다색 이미지인 경우 `null` 이므로 대신 `placeholder` 를 흐릿한 배경으로 사용하십시오.
- 더 작은 이미지가 필요한 경우, 공개 이미지 URL 끝의 `/public` 을 `/w=800,fit=scale-down` 과 같은 변형으로 교체하십시오.
- 사이트에서 이미지에 워터마크를 적용하는 경우, `url` 은 이미 워터마크가 적용된 버전입니다.

## 형식

블로그 게시물은 `fieldData.content` 에 Markdown을 반환하며, 구조화된 `segments` 및 제목의 `toc` 를 추가로 반환합니다. `formats=html,plaintext` 를 추가하면 `contentHtml` 및 `plaintext` 도 가져올 수 있습니다. `segments` 는 기사를 Markdown과 포함된 블록(CTA, FAQ, 갤러리 등)으로 분할하므로 각 블록을 자체 컴포넌트로 렌더링할 수 있습니다.

## 게이트 콘텐츠

컬렉션이 멤버나 구매자로 필드를 제한하는 경우, 익명 읽기에서는 해당 필드가 생략되고 `access` 가 포함됩니다. 예: `{ "granted": false, "gated": ["content"], "requires": { "kind": "entitlement", "featureKey": "premium" } }`。로그인한 고객의 `knr_cat_` 토큰을 보내 전체 항목을 가져오십시오. 각 항목의 `access` 를 기반으로 렌더링하십시오.

## 초안

`preview=1` 을 추가하고 서버에서 `X-Kanorio-Preview: knr_pv_...` 를 보내 게시되지 않은 초안을 읽을 수 있습니다. [인증](https://kanorio.com/ko/developers/authentication)을 참조하십시오.