API 参考

分页

所有 Kanorio API 的列表端点均采用 limit 与 cursor 参数，并返回 data、hasMore 与 nextCursor。

Management API、Content Delivery API 以及 Customer API 的所有列表端点均采用相同的分页方式。

请求

参数	类型	默认值	备注
`limit`	整数	20	范围从 1 到 100。部分端点会标注较低的上限。
`cursor`	字符串	无	来自前一页的 `nextCursor`。第一页请省略此参数。

响应

{
  "data": [{ "id": "post_example01" }, { "id": "post_example02" }],
  "hasMore": true,
  "nextCursor": "eyJvIjoyMCwicyI6ImFiYzEyMyJ9"
}

字段	类型	备注
`data`	数组	此页面的项目，按照端点的顺序排列。
`hasMore`	布尔值	当还有下一页时为 `true`。
`nextCursor`	字符串或 null	将其作为 `cursor` 传入以获取下一页。最后一页时为 `null`。

部分端点会在这些字段之外新增其他字段。例如，集合项目（collection items）会新增 assets，这是一个包含该页面所引用之所有图片与文件的映射表（map）。

规则

游标（Cursors）是不透明的。 请勿解析、构建或长时间存储它们。其格式可能会在未经通知的情况下变更。
保留其他参数。 游标仅适用于发出该游标时所使用的筛选条件、排序与限制。若在发送游标时使用不同的筛选条件，将会返回 400 INVALID_CURSOR。当筛选条件变更时，请重新开始，不要使用游标。
不支持页码或偏移量。 API 不接受 page、pageSize 或 offset。
默认不提供总数。 计算每一笔符合的项目成本高昂，因此列表不会返回总数。Content Delivery API 有两个端点在您传入 total=true 时会返回 total：集合项目，以及搜索（总数与结果在同一次查询中算出）。
短列表仍使用封装格式。 具有小型固定上限的列表（例如 Webhook 端点或重定向）会将所有内容返回在单一页面中，并将 hasMore 设为 false。相关参考页面会对此进行说明。

读取每一页

curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

# then, while hasMore is true
curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50&cursor=eyJvIjo1MH0" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

SDK 的 paginate 会为您追踪 nextCursor，并适用于任何列表端点：

import { createManagementClient, paginate } from "@kanorio/sdk";

const client = createManagementClient({ token: process.env.KANORIO_TOKEN! });

for await (const post of paginate((cursor) =>
  client.get("/sites/{id}/posts", { params: { id: "ws_example123" }, query: { limit: 50, cursor } })
)) {
  console.log(post.slug);
}

当您需要将整个列表作为数组获取时，请使用 listAll 取代 paginate。