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)

條件使用括號標記法：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`	參照，透過參照項目的別名 (slug)	`filter[teacher][eq_slug]=ada`
`has_slug`	多重參照，透過別名 (slug)	`filter[categories][has_slug]=recipes`

slug、publishedAt、createdAt 與 updatedAt 在每個集合中皆可篩選。日期接受相對值，例如 now-30d 或 now+1w。參考文件列出了條件與值的確切限制。

排序 (Sort)

sort=-publishedAt,title 可依最多數個欄位進行排序。開頭的 - 代表降序。純量欄位與上述項目屬性皆可排序。富文本、JSON、媒體與多值欄位則無法排序。

欄位 (Fields)

fields=title,excerpt,cover 僅會回傳 fieldData 中的指定鍵值。id、slug、publishedAt 與 updatedAt 永遠會回傳。請在列表頁面使用此功能，以避免下載每篇文章的完整內容。

展開 (Expand)

expand=teacher 可取代一層參考查詢。每個項目會取得包含參考項目的 expanded.teacher，其影像會加入頂層的 assets 對應表。在 blog 中，expand=authors,categories,tags 會展開文章的作者、分類與標籤，而 primary_author 與 primary_category 會提供您各類別的第一個項目。

資源 (Assets)

影像、圖庫與檔案欄位會儲存資源 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 是一個微小的模糊預覽圖，適用於 blur-up <img> 或 Next.js 的 blurDataURL。
focus 是 0 到 1 座標的焦點。當您進行裁切時，請將其用於 object-position。若未設定，則為 null。
edgeColor 是四個邊緣共用的純色，例如產品照片背後的白色。當您以 object-fit: contain 顯示影像時，可將其作為背景。對於透明或多色影像，此值為 null；請改用 placeholder 作為模糊背景。
若要取得較小的影像，請將公開影像網址末尾的 /public 替換為變體，例如 /w=800,fit=scale-down。
當網站對影像進行浮水印處理時，url 即為已加上浮水印的版本。

格式 (Formats)

部落格文章會在 fieldData.content 中回傳 Markdown，並包含結構化的 segments 與標題的 toc。加入 formats=html,plaintext 即可額外取得 contentHtml 與 plaintext。segments 會將文章拆分為 Markdown 與嵌入區塊（例如行動呼籲、FAQ 與圖庫），讓您能使用自己的元件渲染每個區塊。

受限內容 (Gated content)

當集合將欄位限制為僅限會員或購買者存取時，匿名讀取會省略這些欄位並包含 access，例如 { "granted": false, "gated": ["content"], "requires": { "kind": "entitlement", "featureKey": "premium" } }。請發送已登入顧客的 knr_cat_ 權杖以取得完整項目。請根據每個項目自身的 access 進行渲染。

草稿 (Drafts)

加入 preview=1 並從您的伺服器發送 X-Kanorio-Preview: knr_pv_... 即可讀取未發佈的草稿。請參閱驗證。