> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 分页

> 从 YCloud 列表端点获取完整的结果集。

## 功能简介

分页允许你在有界限的响应中获取庞大的数据集合。YCloud 列表端点使用页码分页或游标分页。

## 准备工作

查阅端点参考文档，了解其支持的分页参数、筛选条件、排序方式以及响应结构。不要假定每个列表端点都使用相同的策略。

## 工作原理

请求一页数据，处理其中的条目，并持续进行，直到响应表明不存在下一页。在整个遍历过程中，请保持相同的筛选和排序设置。

## 请求与响应

### 页码分页

大多数列表端点支持以下查询参数：

| 参数 | 说明 |
| - | - |
| `page` | 页码。从 `1` 开始，默认值为 `1`。 |
| `limit` | 每页结果数。取值范围为 `1` 到 `100`，默认值为 `10`。 |
| `includeTotal` | 设置为 `true` 以包含匹配条目的总数。 |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/contact/contacts?page=1&limit=100&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

分页响应包含：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "offset": 0,
  "limit": 100,
  "length": 2,
  "total": 2,
  "items": [{ "id": "ITEM_1" }, { "id": "ITEM_2" }]
}
```

| 响应字段 | 含义 |
| - | - |
| `items` | 此页面返回的对象。 |
| `offset` | 从零开始的起始位置：`(page - 1) * limit`。 |
| `limit` | 请求的每页大小。 |
| `length` | 实际条目数，等于 `items.length` 且不大于 `limit`。 |
| `total` | 匹配的总条目数；仅在 `includeTotal=true` 时返回。计数会增加延迟，因此请仅在需要时请求。 |

<Note>
  基于偏移量的端点通常会将 `page` 和 `limit` 的上限限制为 100，从而将
  遍历限制在前 10,000 个条目内。请检查每个端点的限制，并在端点支持
  游标分页且你需要更大的结果集时使用游标分页。
</Note>

当 `length` 等于 `limit` 时继续请求下一页。当 `length` 小于 `limit` 时停止。

### 游标分页

返回 `cursor.after` 的端点支持游标分页。在下一次请求中将该值作为 `pageAfter` 传入。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/unsubscribers?limit=100&pageAfter=id%3Afoo" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

游标响应包含 `items`、`limit`、`length`，并在存在更多结果时包含 `cursor.after`。仅支持游标分页的端点才会返回 cursor 对象。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [{ "id": "ITEM_1" }],
  "limit": 1,
  "length": 1,
  "cursor": { "after": "id:foo" }
}
```

将返回的游标原样传给下一个请求。将其视为不透明标识；请勿修改它或将其作为应用程序的长期标识符进行存储。当 `length` 为 `0` 或响应中不再包含 `cursor.after` 时停止。

<Note>
  分页和筛选参数因端点而异。在实现列表操作之前，请查阅 API 参考文档。
</Note>

## 实现检查清单

* 显式设置 `limit`，而不是依赖默认值。
* 在各页面请求之间保持筛选条件一致。
* 依据响应条件停止请求，而不是依据猜测的页数。
* 将第一页为空视作成功的结果进行处理。
* 为后台任务添加最大页数或条目数防护限制。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.