# ページネーション

> KanorioのすべてのAPIのリストエンドポイントでは、limitとcursorを使用してデータを取得し、hasMoreとnextCursorを返します。

> Markdown version of https://kanorio.com/ja/developers/basics/pagination. 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/pagination.md

Management API、Content Delivery API、Customer APIのすべてのリストエンドポイントは、同じ方法でページネーションを行います。

## リクエスト

| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
| `limit` | 整数 | 20 | 1から100まで。一部のエンドポイントでは、より低い上限が設定されています。 |
| `cursor` | 文字列 | なし | 前のページの`nextCursor`。最初のページでは省略してください。 |

## レスポンス

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

| フィールド | 型 | 備考 |
|---|---|---|
| `data` | 配列 | エンドポイントの順序に従った、このページのアイテムです。 |
| `hasMore` | 真偽値 | 次のページが存在する場合に`true`となります。 |
| `nextCursor` | 文字列またはnull | 次のページを取得するために`cursor`として渡します。最後のページでは`null`になります。 |

一部のエンドポイントでは、これらに加えてフィールドが追加されます。例えば、コレクションアイテムのエンドポイントでは、ページ内で参照されているすべての画像やファイルをマップ形式でまとめた `assets` フィールドが追加されます。

## ルール

- **カーソルは不透明な値です。** 解析、構築、または長期保存は行わないでください。カーソルの形式は予告なく変更される可能性があります。
- **他のパラメータを維持してください。** カーソルは、それが発行された際のフィルタ、ソート、制限設定に紐付いています。異なるフィルタでカーソルを送信すると `400 INVALID_CURSOR` エラーが返されます。フィルタを変更する場合は、カーソルを使用せずに最初からやり直してください。
- **ページ番号やオフセットは使用しません。** APIは `page`、`pageSize`、`offset` を受け付けません。
- **デフォルトでは合計数は返されません。** すべての一致件数をカウントすることは負荷が高いため、リストは合計数を返しません。Content Delivery APIでは、コレクションアイテムと検索の2つのエンドポイントが、`total=true` を渡すと `total` を返します（検索の合計数は結果と同じクエリで算出されます）。
- **短いリストでもエンベロープを使用します。** Webhookエンドポイントやリダイレクトなど、上限が小さく固定されているリストであっても、`hasMore: false` を含めて1ページですべての結果を返します。詳細については各リファレンスページを参照してください。

## すべてのページを読み取る

```bash
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` を自動的に追跡し、すべてのリストエンドポイントで動作します。

```ts
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);
}
```

リスト全体を配列として取得したい場合は、`paginate` の代わりに `listAll` を使用してください。