分頁

列表端點的 API 以分頁方式回傳資料。平台歷史上形成了兩種分頁方式;具體方式在互動式參考文件中各端點說明頁面有所標示。

方式一 — 偏移量與 X-Total-Count

傳統的偏移分頁。請求接受查詢參數 limit(每頁數量)與 offset(跳過的記錄數):

curl -H "Authorization: Bearer mbp_你的_TOKEN" "https://你的網域/api/bots/BOT_ID/subscribers?limit=50&offset=100"

總記錄數透過回應標頭 X-Total-Count 回傳。可由此計算總頁數:每次將 offset 增加 limit,直到 offset 小於 X-Total-Count。回應主體為當前頁的元素陣列。

方式二 — before 游標與 has_more

適用於依時間排序的資料流(例如對話訊息)的游標分頁。請求接受 limit 及可選的游標 before——即最後一個已取得元素的識別碼或標記:

curl -H "Authorization: Bearer mbp_你的_TOKEN" "https://你的網域/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

回應包含一頁資料及 has_more 標誌。當 has_moretrue 時,繼續請求並將最後一個元素的游標傳入 before;當 has_morefalse 時,即為最後一頁。

如何選擇方式

你無需自行選擇——由端點決定。參考列表通常使用偏移量與 X-Total-Count;時間排序的資料流使用 before 游標與 has_more。請務必查閱參考文件中對應端點的說明頁面。

延伸閱讀