API 레퍼런스

필터링, 필드 및 확장

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

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

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 맵이 포함되어 있으므로 두 번째 요청이 필요하지 않습니다.

{
  "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_... 를 보내 게시되지 않은 초안을 읽을 수 있습니다. 인증을 참조하십시오.