# 篩選、欄位與展開

> 在 Content Delivery API 讀取中進行篩選、排序、投影欄位、展開參考與解析媒體，每頁僅需一個請求。

> Markdown version of https://kanorio.com/zh-Hant/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)

條件使用括號標記法：`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` 對應表來解析這些資源，因此您永遠不需要發送第二次請求。

```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` 是一個微小的模糊預覽圖，適用於 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_...` 即可讀取未發佈的草稿。請參閱 [驗證](https://kanorio.com/zh-Hant/developers/authentication)。