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

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] のように条件をグループ化します。

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回目のリクエストは不要です。

{
  "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_... を送信すると、未公開のドラフトを読み取ることができます。認証を参照してください。