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_... 即可读取未发布的草稿。请参阅验证。