# フィルタリング、フィールド、展開

> Content Delivery APIの読み取り時に、フィルタリング、ソート、フィールドの投影、リファレンスの展開、メディアの解決を行い、ページごとに1回のリクエストで効率的にデータを取得します。

> Markdown version of https://kanorio.com/ja/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` マップが含まれているため、2回目のリクエストは不要です。

```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/ja/developers/authentication)を参照してください。