分页 - YCloud Docs

功能简介

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

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

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

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

curl "https://api.ycloud.com/v2/contact/contacts?page=1&limit=100&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"

分页响应包含：

{
  "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` 时返回。计数会增加延迟，因此请仅在需要时请求。

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

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

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

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 对象。

{
  "items": [{ "id": "ITEM_1" }],
  "limit": 1,
  "length": 1,
  "cursor": { "after": "id:foo" }
}

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

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