GetMyBot 知識庫

分頁

分批取得較長的清單而不漏掉記錄:每頁大小、offset 位移,以及 before 游標。

本頁內容

API 會把客戶、訊息等長清單分批回傳,每批稱為一頁。讀取後續頁面的做法叫分頁,可避免單次請求載入整份歷史。

有兩種延續方式:跳過已讀取的記錄數(位移),或傳入上次讀到的位置(游標)。每個 API 端點支援哪一種,以參考文件為準。

方法一:offset 和 X-Total-Count

limit 是希望每頁取得的數量,offset 是要跳過的記錄數。limit=50&offset=100 表示跳過前 100 筆,最多讀取接下來的 50 筆:

curl -H "Authorization: Bearer <個人權杖>" \
  "https://你的網域/api/bots/BOT_ID/users?limit=50&offset=100"

回應標頭 X-Total-Count 是總筆數,內容是目前頁面的陣列。每次將 offset 增加實際收到的筆數,並與 X-Total-Count 比較,直到讀完。

offset 有上限

在支援位移的端點,offset 超過 100,000 會回傳 400,回應會建議縮小篩選條件或改用游標。大位移也會增加資料庫處理量,因為資料庫仍須讀取被跳過的記錄。若清單超過 100,000 筆,可按日期、頻道或狀態縮小範圍;端點支援時改用游標;要取得完整資料時使用該區域的匯出功能。

各端點的 limit 上限不同

limit 沒有統一最大值,不同清單可能是 200、500 或 1,000。請查看各端點說明。要求超過上限時,有些端點會以 400 拒絕,例如「limit must be at most 500, got 5000」;其他端點會不提示而改用預設值,通常是 100。

因此不要假設實際收到的頁面與要求的大小相同。請按回傳陣列的實際長度推進 offset。若要求 5,000 筆卻只收到 100 筆,直接增加 5,000 就會漏掉 98% 的資料。也不要只以空頁判斷結束,應同時看 X-Total-Count 和實際筆數。

方法二:before 游標和 has_more

按時間排序的清單,例如對話訊息,可能支援游標。before 是最後一筆已取得記錄的 ID 或位置標記:

curl -H "Authorization: Bearer <個人權杖>" \
  "https://你的網域/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

回應包含一頁資料及 has_more。若為 true,把本頁最後一筆的游標放入下一次請求的 before;變成 false 時,就已讀到最後一頁。

應使用哪種方法

由端點決定,不能任意選擇。一般參考清單多使用位移和 X-Total-Count,時間序列多使用 before 和 has_more。請以端點說明為準。

下一步